Cream of the Crop 1

home *** CD-ROM | disk | FTP | other *** search

/ Cream of the Crop 1 / Cream of the Crop 1.iso / DISK / DCOMDOC.ARJ / MACRO.DOC < prev

Wrap

Text File | 1991-12-13 | 426KB | 9,063 lines

dCOMdCOM Macro ProgrammingMacro Programming MenuingMenuing Access ControlAccess Control Shareware Version 4.0 Copyright (c) 1991, Dave Frailey and DAC Micro Systems Information in this document is subject to change without notice. Neither the owner or distributors make any expressed or implied warranties with regard to this software, including merchantability, applicability for any purpose or non-infringement of patents, copyrights or other proprietary rights of others. This software is provided "as is" without warranty of any kind. In no event will the owner or distributors be liable to you for any damages, including any lost profits, lost savings or other incidental or consequential damages arising out of the use or inability to use this software. dCOM is not, nor has it ever been, public domain or free software. It is distributed in two forms: 1) under the User Supported software concept (Shareware) or, 2) in pre-paid form complete with typeset documentation, quick reference cards, and user registration. Non- registered users of dCOM are granted a limited license to use dCOM for a trial period not to exceed 30 days, in order to determine if it suits their needs. Any other use of dCOM or use past this period, requires registration. All users are granted a limited license to copy dCOM only for the purpose of allowing others to try it, subject to the above restrictions as well as these: 1) dCOM must be distributed in absolutely unmodified form, including ALL program files, documentation files, and other files. dCOM may not be included with any other product for any reason whatsoever without a license from DAC Micro Systems. No charge or payment may be levied or accepted for dCOM (except that recovered for media and operating costs). Bulletin Board system operators may post dCOM on their BBS for downloading by their users without written permission only if the above conditions are met, and only if no special fee is necessary to access the dCOM files (a general fee to access the BBS is acceptable). All DAC Micro Systems products are trademarks or registered trademarks of DAC Micro Systems. Other brand and product names are trademarks or registered trademarks of their respective holders. Copyright (c) 1991, Dave Frailey and DAC Micro Systems. All rights reserved. DAC Micro Systems 40941 176th St E Lancaster, CA 93535 Voice: 805/264-1700 BBS: 805/264-1219 i REGISTRATIONREGISTRATION Registering dCOM allows you to use this product after the trial period expires for an indefinate period of time. Registered dCOM users get mailed notifications of dCOM updates and registered user access when calling the dCOM Support BBS. Most importantly, registered users know they are helping to ensure that high-quality software like dCOM can continue to be distributed in this low-cost manner. For more information on ordering, refer to the REGISTER.DOC text file included with this package or, call the dCOM Support Board for on-line ordering. This document file is an abridged version of the registered user's type-set documentation. There are many more macro commands and variables than are documented here. This documentation is only meant to provide you with enough familiarity so that you can determine whether dCOM suits your taste or requirements. It is no way meant to provide you with a reason to continue using dCOM on an indefinate basis without registering. PREFACEPREFACE Webster's definition of the word "macro" in a computer-related context is described as "a single computer instruction that stands for a sequence of operations". When a program provides an automated facility where a sequence of operations can be programmed by the user, a lot of programs today are calling this capability a "script". The term "macro" now seems to have been relegated to something that only plays-back (or simulates) keyboard keystrokes. In dCOM's case however, the term "macro" refers to an extensible programming language, not to keystroke playback. A long time ago in a land far, far away (roughly five years now), when dCOM was just a twinkle in its father's eye, the term script was hardly a common term in the PC environment. And now, after thinking about it, "macro keys" sounds a lot better than "script keys". ii ContentsContents PREFACE........................................................II INTRODUCTION....................................................1 USING MACRO KEYS................................................4 General Overview.............................................5 From the File Handler........................................7 MACRO FILES.....................................................8 Overview.....................................................9 Editing.....................................................10 File Format.................................................11 Menu Title................................................12 Comments..................................................12 AUTOEXEC.MAC................................................13 LOGIN.MAC...................................................14 MACRO KEY DEFINITIONS..........................................15 Overview....................................................16 Function Key Definitions....................................16 Title Line Switches.......................................17 Special Definitions.........................................18 [FILEAUTO]................................................19 [MENUAUTO]................................................20 [DRIVEAUTO]...............................................21 [PUBLIC]..................................................21 [EQUATES].................................................22 MACRO LANGUAGE.................................................23 Overview....................................................24 IF Statements...............................................26 In-Line Arithmetic..........................................28 Menus and Windows...........................................29 Menuing Switches..........................................30 Commands....................................................31 Reference.................................................32 Variables...................................................78 User Variables............................................80 Arrays..................................................81 Indirect Assignments....................................81 System Variables..........................................82 Reference...............................................84 Examples...................................................101 Technical Tricks...........................................116 MENUING.......................................................119 Overview...................................................120 The Menu Mode..............................................121 Controlling Menu Appearance................................122 Include Files..............................................123 iii ACCESS CONTROL................................................125 Overview...................................................126 Enabling...................................................127 Logging In.................................................128 Logging Out................................................129 Administration.............................................130 Rights...................................................131 Groups...................................................132 With the Macro System......................................133 APPENDICES....................................................134 Appendix A - Using Macro Files on a Network................135 Appendix B - Batch File Interchangeability.................138 Appendix C - The Internal Macro Compiler...................139 Appendix D - ANSII Music...................................140 Appendix E - Macro Error Numbers...........................141 INDEX.........................................................142 iv ====================================================================== INTRODUCTIONINTRODUCTION ====================================================================== 1 Introduction ---------------------------------------------------------------------- IntroductionIntroduction One of the most powerful features in dCOM is its macro facility. It can be used in a manner as simple as that of a MS-DOS batch file or, as complex as developing an interactive application in a high-level programming language. The choice is yours. If programming isn't your 'bag', you can still access a lot of the macro key functionality by only going so far as to import some of your common batch files into a dCOM macro file so they can be accessed just by pressing one of the 20 function keys. The macro language however, can become a lot more than just having 20 different batch files on-line and ready to be executed at the touch of a key. They can be programmed to react interactively with the file handler, using the currently selected file, loop around tagged files, or get keyboard input, test and jump conditionally on a variety of operands, etc.... To begin using them though, all you have to know is how to write a simple batch file with a text editor. By going a little further and learning a few of the macro commands you can soon be writing macro keys that: * Pop up menus that select files or directories before running a program, or performing some other action on the item selected. * Pop up menus of your own design which you can use to control macro execution flow or branching. * Pop up menus of commonly used applications which are then executed simply by selecting one from the menu. * Use both single-line IF statements and also nestable IF blocks which have a full compliment of IF..THEN, ELSE/ELSEIF, and ENDIF statements. * Use nestable DO blocks which loop sequentially around each file (or directory) that qualifies based on a given mask. dCOM can also be made to initially act as a front-end, mouse-sensitive menu system (instead of starting up as a file handler), by passing it the /M command line switch. Since the macro system can branch off into other macro files, it is easy to build a sophisticated cascading submenu structure. For more information refer to Menuing on page 119. The behavior of each individual macro key can be customized with title line switches. For instance, if a macro key needs to temporarily load a TSR that is needed by a subsequent program that the macro key will run, but you don't need the TSR when the macro key finishes, you can 2 Introduction ---------------------------------------------------------------------- give the macro key a /R title line switch to have the TSR removed without impacting any other TSR's loaded previously. Each individual macro key can be protected by the login (access control) system. If the login system is active and the current user doesn't belong to a group that has access to a protected macro key, the user won't see the option and can't execute the macro key. For more information refer to the /G title line switch. Each macro key can also be protected with its own unique password. When an attempt is made to run that macro key, a box pops-up asking the user to enter the appropriate password. Macro keys can be called from the Alarm system and also by the Extension Execute Feature of the file handler. Refer to the file handler's documentation for more information. The design of the macro system was with speed, efficiency, and flexibility as primary factors. Each macro file is automatically compiled and 'tokenized' by an internal process to a binary load image file when the ASCII macro file is changed. The compiled macro files are read into memory directly when they haven't been changed. Compiling the macro files yields a performance level almost equivalent to a program intelligently developed in assembler. dCOM as a whole (including the macro system), always reads files in a sharing mode with as large a block size as possible. Reading files in a few (or one) large blocks is much more efficient than reading files in many smaller blocks, especially one byte at a time in character or line-oriented disk I/O. The capabilities provided by dCOM's macro system are unrivaled and unparalleled in the PC world today. 3 ====================================================================== USING MACRO KEYSUSING MACRO KEYS ====================================================================== 4 Using Macro Keys - General Overview ---------------------------------------------------------------------- Using Macro Keys General OverviewUsing Macro Keys General Overview This section provides basic information about using the macro system in general. It is applicable to all modes in which it might be used. The basic steps to building and using macro keys are: * Understanding the format of a macro file. * Create and edit a macro file (usually the first one you build is DCOM.MAC). * Start pressing function keys. When you want the macro keys to act as a front-end menu (without the file handler), start dCOM with a /M command line switch. This is called the Menu Mode and is discussed in more detail under Menuing on page 119. When a menu of the macro key titles is displayed on the screen (either because the menu mode is active, or the Backspace key was pressed in the file handler), a macro key can be selected and executed in several ways: * You can always just press the appropriate function key. * If you like the mouse, you can click the left button on the title of the key you want to execute. * If you like to use the cursor keys, you can use the keypad arrow keys to move the selection bar (it won't appear until the first time you use one of the arrow keys) to the title of the key you want, and then press Return. * You can press the first letter of a macro key's title and the selection bar will highlight the first one found. If more than one macro title begins with the same letter, press the letter again until the right title is selected - then press Return. When a macro key is executed, dCOM automatically manages when and if the screen is initially cleared. There is no need to start a macro key with a CLS instruction just to remove the file handler or menu mode's screen. For example, if all a macro key does is change directories, the screen will never clear automatically, making the transition almost seamless. Pressing Ctrl-C will abort macro execution as long as the macro is not running another program. If a macro is running another program and the Ctrl-C causes the program to terminate, the macro key will also 5 Using Macro Keys - General Overview ---------------------------------------------------------------------- terminate. dCOM's background keyboard handler always knows when a Ctrl-C sequence has been pressed. The macro engine running in the foreground checks the background handler for a Ctrl-C every time it executes a new line. All macro commands that pause for keyboard input will react to the Escape key by aborting execution of the current macro definition. This includes all of the menuing-type commands as well. This action can be circumvented however, by trapping the Escape key with an ONBREAKGOTO macro command. When the macro system encounters an error during the execution of a macro, a message will pop-up with a beep describing the error and the line that produced it. After you cancel the message by pressing Return or Escape, the macro will terminate and control will return to either the file handler or menu mode. Sometimes you may need a macro key to display a pause message when it terminates so that what it has displayed won't be immediately covered by the file handler's screen or the menu mode's screen. This is usually the case when a macro runs a program that displays something, but didn't prompt for any type of response before it exited. In a batch file you could use a PAUSE command as the last statement to do this (which you can also do with a macro key), but there is also a macro title line switch, /W, which does this in a slightly more aesthetic manner and allows the file handler to concurrently reload its overlay (if necessary) in the meantime. There are several other title line switches available that allow you to customize the behavior of each individual macro key. For more information refer to Title Line Switches on page 17. Available disk space is the only limiting factor to how many different macro files you can create and use. By default, DCOM.MAC is the first one loaded and active. From the file handler you can temporarily branch off to a macro file different from the currently active macro file by using its "/" command. From within the menu mode, you would have to build options to call other macro files by using macro keys in the current macro file to branch to them. For instance, you could build a macro file that performs all of your disk utility functions (like formatting, copying, etc...) and then quickly call it up by pressing the "/" key and selecting that macro file from the pop-up menu. The point is, if you have a lot of varied and different things for macro keys to do, its probably a good idea to separate them logically into different macro files. 6 Using Macro Keys - From the File Handler ---------------------------------------------------------------------- Using Macro Keys From the File HandlerUsing Macro Keys From the File Handler This section discusses the macro system while the file handler is active. For information on using the macro system when the Menu Mode is active, refer to Menuing on page 119. Anytime the file handler is in its main screen (where you copy, delete, rename, etc...), you can execute a macro key just by pressing its function key. If you can't remember which function key executes the macro you want, you can press the Backspace key to get a quick pop-up overlay of the macro key titles. The pop-up overlay reacts to all of the methods of triggering a macro key that are described under General Overview. You can temporarily call (gosub) a different macro file by pressing the "/" (forward slash) key. A pop-up menu of that macro file's titles will then display in the same manner as if you had pressed the Backspace key. The original macro file will be automatically reloaded if you Escape the menu or after you run one of the macro keys displayed. For mouse users, clicking the mouse left button on the "M- File" option in the sidebar menu has the same effect as pressing the "/" key. You can permanently change (goto) to a different macro file by pressing the "." (period) key. When the "." key is used to change macro files, the macro menu overlay is automatically invoked to help you make a selection from the new macro file (unless you are returning to the original default macro file). When you are done with the new macro file's overlay menu though, the new macro file will stay loaded in memory until you change it again with the "." command. When a different macro file is active than the original default macro file, the bottom right corner of the file handler's screen (the Drive Select Box) will constantly display the name of the current macro file to help remind you that a different set of macro keys is active than that which you're probably used to. Several system variables are provided that facilitate writing a macro key so that it can work interactively with the file handler. They allow you to write macro keys that know the name of the currently selected file, or tagged files. The most common of these are %FN, %FE, %TN, and %TE. For more information refer to Macro Variables on page 78 7 ====================================================================== MACRO FILESMACRO FILES ====================================================================== 8 Macro Files - Overview ---------------------------------------------------------------------- Macro Files OverviewMacro Files Overview dCOM macro files are ASCII text files which can be subdivided into as many as 20 different macro key definitions (F1 through F10, and Shift- F1 through Shift-F10). Along with the 20 function keys, some additional special definitions are provided that allow you to define macro code which executes automatically under certain conditions. Macro key definitions are described in the next section. Macro files can be edited with any text editor. But, if you edit the currently active macro file with a text editor other than dCOM's internal editor, new changes won't be detected until dCOM changes macro files or you restart dCOM. The first permanent macro file loaded initially by default is DCOM.MAC unless otherwise specified with the /MF=macrofile command line switch when dCOM is run. There are some special macro files which dCOM will automatically run under certain conditions (e.g. AUTOEXEC.MAC and LOGIN.MAC), if they exist. They are further described later on in this section. Macro files are assumed to be located in the same drive and subdirectory in which dCOM is installed (the Home Directory), unless a specific path is given to the contrary. Macro files must have a .MAC extension. All commands that deal with macro filenames will automatically append a .MAC extension if it is not given or, if a different extension is specified. The ASCII macro files are automatically compiled and tokenized on-the- fly when they have been modified. Label references are also resolved by the compiler to further optimize the runtime environment. The internal macro compiler uses a form of turbo indexing, which in most cases compiles a macro file so fast that its hard to notice it even occurred. The compiler is internally invoked when an attempt is made to load a macro file that's been modified since the last time it was compiled. This is detected by comparing the date of the ASCII macro file against the date of the compiled macro file (compiled macro files are hidden files which have the same name as the ASCII .MAC file, but have a .CMF extension). 9 Macro Files - Editing ---------------------------------------------------------------------- Editing a Macro FileEditing a Macro File To facilitate editing a macro file when the current drive or directory is not where dCOM is installed, the file handler provides a convenient command (Alt-K) which allows you to quickly select and edit existing macro files in dCOM's Home Directory, or to create a new macro file in that directory. After you select a macro file with Alt-K, dCOM invokes its text editor and loads the macro file into the next available buffer. If you had previously quit the editor with its Alt-Q command, previously edited files are still loaded in the editor and can be accessed by pressing F2, F3, or F4. Using dCOM's Text EditorUsing dCOM's Text Editor Once inside dCOM's editor, its use is fairly straight-forward. Use the cursor (arrow) keys to move around and change the file. When finished making changes, use Alt-W to write (save) the file and use Alt-X to exit the editor. If you had started a new file using the "[NewFile]" selection of Alt-K, pressing Alt-W will stop and ask for a filename before proceeding (remember to give it a .MAC extension). Some of the more advanced features are: * Use F8 to mark the starting and ending lines of a block for subsequent copying or moving with Alt-C or Alt-M respectively. (You can also mark lines by holding the Shift key down while moving the cursor keys.) * Press F7 or Alt-H to bring up the editor's help screen. * Use Alt-D or Alt-I to delete a line or insert a line. (Notice how everything correlates...?) To delete characters, use the Del key. To change the insert/overtype mode, use the Ins key. * You can open (or switch to) other windows by using the function keys F2, F3 and F4. Another existing file can be loaded into a different window using the Alt-E command. Blocks of text from the new window may be copied or moved from window to window by using F8 to mark the source lines, switch to the destination window (using F1 through F4), and then using the Alt-C or Alt-M commands, respectively. 10 Macro Files - File Format ---------------------------------------------------------------------- Macro File FormatMacro File Format An example of the basic format of a simple macro file is: ,---------------------------------------------------------------------, MAIN MACRO'S ;;MENU TITLE | | | | [F1] MS-WORD ;;TITLE LINE AND SWITCHES | | C: ;;CHANGE DRIVES (IF NEC) | | CD \MSWORD ;;CHANGE DIRECTORIES | | WORD ;;RUN MS-WORD | | CD C:\ ;;CHANGE C: BACK TO ROOT DIR | | CDDO ;;RETURN TO ORIG DRIVE & DIR | | | | [F2] dBASE ;;TITLE LINE AND SWITCHES | | C: ;;CHANGE DRIVES (IF NEC) | | CD \DBASE ;;CHANGE DIRECTORIES | | DBASE ;;RUN dBASE | | CD C:\ ;;CHANGE C: BACK TO ROOT DIR | | CDDO ;;RETURN TO ORIG DRIVE & DIR | | | | . | | . | | . | | | | [sF10] WORDSTAR ;;TITLE LINE AND SWITCHES | | C: ;;CHANGE DRIVES (IF NEC) | | CD \WS5 ;;CHANGE DIRECTORIES | | WS ;;RUN WORDSTAR | | CD C:\ ;;CHANGE C: BACK TO ROOT DIR | | CDDO ;;RETURN TO ORIG DRIVE & DIR | | `---------------------------------------------------------------------' The format of a macro file is very "loose". The one shown above is only an example. It has the body of each macro key indented one tab stop and has comments on each line - neither of which are necessary. The use of lower or upper case is subjective. dCOM is always insensitive to the use of case. Blank lines have no functional significance and consume no memory. Use them as desired to aid in readability. Leading and trailing spaces are ignored and consume no additional memory (indent to your hearts content for purposes of clarity). 11 Macro Files - File Format ---------------------------------------------------------------------- Menu TitleMenu Title The first non-blank line encountered before the start of any macro key definition is considered the menu title, with one exception - the macro INCLUDE command. Most likely you won't use an INCLUDE statement as the first significant line in a macro file, but if you do, you'll then have to use an explicit MENUTITLE statement on a subsequent line to define the menu title. Each macro file can only have one menu title. The menu title has a maximum displayable length of 40 characters. It is displayed centered in the top of the macro menu, above the macro key titles. A menu title can include macro variables. CommentsComments Comments in a macro file are supported but not required. They begin when two semicolons are encountered in sequence and automatically terminate when the end of line is encountered. Comments (and tabs or spaces leading to a comment) are ignored when the macro file is compiled and consume no additional memory. If a comment starts at the beginning of a line, a single semicolon is all that is needed to start the comment. Using two semicolon's will have no adverse affect however. 12 Macro Files - AUTOEXEC.MAC ---------------------------------------------------------------------- AUTOEXEC.MACAUTOEXEC.MAC If there is a file called AUTOEXEC.MAC in dCOM's Home Directory, it will be called and executed automatically when dCOM starts up. It is executed only once, before any other macro files which might be set to run with a /MF, and /F# command line switches. AUTOEXEC.MAC does not execute when a multiple copy of dCOM is being run. When AUTOEXEC.MAC is executed, it normally doesn't have any affect on what ends up as the default macro file unless it itself changes the current macro file with a GOTOMF command. The format of AUTOEXEC.MAC does not require a title line like normal macro files. Without a title line, its contents are automatically assumed to be the F1 key, which is the key dCOM executes when it runs AUTOEXEC.MAC. If you define other keys subsequently within AUTOEXEC.MAC, they won't run automatically, but they could be called by the main macro body. Normally you just write it like a normal batch file with what you want executed, (of course all of the extended macro commands are also available). Macro code executes much faster than batch files do, so if you run dCOM as your primary shell you may want AUTOEXEC.MAC doing most of the things AUTOEXEC.BAT would do. If your are running dCOM as the primary shell, TSR's should not be loaded in either the AUTOEXEC.BAT or AUTOEXEC.MAC, they should be loaded by AUTOLOAD.SYS. Refer to the dCOM User's Guide for more Information. 13 Macro Files - LOGIN.MAC ---------------------------------------------------------------------- LOGIN.MACLOGIN.MAC When the Login system is active (dCOM's /L command line switch), and if there is a file called LOGIN.MAC in dCOM's Home Directory, it will be loaded automatically as the current macro file when a new user logs in (any macro files saved on the gosub stack are discarded). If the Login system is not active, the existence of LOGIN.MAC has no affect. If you wish to automatically execute some macro code immediately after a new login (for instance to then load a personalized macro file depending on who the user is), write the macro code under a [FILEAUTO] definition in LOGIN.MAC. 14 ====================================================================== MACRO KEY DEFINITIONSMACRO KEY DEFINITIONS ====================================================================== 15 Macro Key Definitions ---------------------------------------------------------------------- Macro Key Definitions OverviewMacro Key Definitions Overview A macro file is logically separated by one or more definitions. Function key definitions define a portion of the macro file that executes when that function key is invoked. Other definitions provide special features and are described a little later on. Function Key DefinitionsFunction Key Definitions Each function key definition is started with a title line that has the following format: [F#] title [/switches] The bracket characters around "F#" are mandatory and serve as a means to identify the start of a new function key definition. The brackets surrounding "/switches" are used to indicate that optional title line switches may be specified after the title. You would not include the brackets if you were using one of the switches. For example: [F1] WordPerfect /w The allowable function key definitions are [F1] through [F10], and [sF1] through [sF10] (the "s" designates shifted function keys). Each function key title has a maximum displayable length of 20 characters; exceeding this only causes it to be truncated. A function key title can include macro variables. The lines that follow the title line are what make up the body of a macro key. There is no command which marks the end of a macro key definition. The next title line of another macro key is the implied end of the preceding macro key (or the end of file). Function key definitions need not be defined in any particular sequence. Defining them out of order however, can have a minor degradation on performance when the macro file is automatically recompiled and, could become somewhat confusing. Duplicate function key definitions are illegal and will produce an error when either one is executed. 16 Macro Key Definitions ---------------------------------------------------------------------- Title Line SwitchesTitle Line Switches The characteristics of each macro key can be altered by the use of optional title line switches. These switches are specified on the same line that defines the macro key, following the text of its title. /W/W Specifies that a pause (wait) is necessary when the macro terminates. This switch is needed when the macro does something that needs to be seen, but whatever did it doesn't wait for user response before exiting (e.g. the MS-DOS DIR command). If you don't tell dCOM that the macro key needs a pause, it will just go ahead and build the screen for whatever comes next, none the wiser that you wanted to read it. An alternate way to achieve this effect, but on a conditional basis, is to not use the /W switch so that overall the macro won't pause, but when you do want it to pause use the %W variable on any macro line that accepts parameters (%W is more like a switch, and used primarily with the Extension Execute feature). /R/R This switch tells dCOM to remove any TSR's loaded by the macro key when the macro key terminates. This is useful if you need to load a TSR to support a program which is also run in the same macro key, but you don't need the TSR after the macro key is finished. /P:pword/P:pword Specifies that the macro key is password protected. The password specified following the colon is then required before a user can execute the macro key. The maximum recognized length of a password is 10 characters. If you use password's on your macro keys, it might be a good idea to hide the macro files (using the file handler's Alt-H command) since the password can easily be seen by viewing the macro file. If you hide a macro file, it will have no ill-effect on any of the commands that involve macro files. 17 Macro Key Definitions - Special ---------------------------------------------------------------------- Special DefinitionsSpecial Definitions Several additional macro definitions may also be defined within a macro file other than function key definitions. These definitions have a syntax similar to function key definitions in that they are surrounded by square brackets - but they normally do not also have a title, or title line switches. For example: ,---------------------------------------------------------------------, MAIN MACRO'S ;;MENU TITLE | | | | [MENUAUTO] ;;RUNS BEFORE MENU DISPLAYS[MENUAUTO] ;;RUNS BEFORE MENU DISPLAYS | | CLS 3,1,176 ;;CLEAR SCREEN IN NICE COLORS CLS 3,1,176 ;;CLEAR SCREEN IN NICE COLORS | | MENUCOLOR 0,3,14,4,1 ;;OVERRIDE DEFLT MENU COLORS MENUCOLOR 0,3,14,4,1 ;;OVERRIDE DEFLT MENU COLORS | | | | [PUBLIC] ;;PUBLIC PROCEDURES[PUBLIC] ;;PUBLIC PROCEDURES | | :SETWINPATH ;;SET WINDOWS PATH PROC. :SETWINPATH ;;SET WINDOWS PATH PROC. | | %TPATH=%[PATH] ;;SAVE CURR PATH IN %TPATH %TPATH=%[PATH] ;;SAVE CURR PATH IN %TPATH | | SET PATH=C:\WINDOWS;C:\WINAPPS\WINWORD ;;SET PATH FOR WIN&APPS SET PATH=C:\WINDOWS;C:\WINAPPS\WINWORD ;;SET PATH FOR WIN&APPS | | SET PATH=%[PATH];C:\WINAPPS\AMIPRO ;;ADD ON PATH FOR AMIPRO SET PATH=%[PATH];C:\WINAPPS\AMIPRO ;;ADD ON PATH FOR AMIPRO | | RETURN ;;RETURN TO CALLER RETURN ;;RETURN TO CALLER | | :RMVWINPATH ;;REMOVE WINDOWS PATH PROC. :RMVWINPATH ;;REMOVE WINDOWS PATH PROC. | | SET PATH=%TPATH ;;RESTORE ORIGINAL PATH SET PATH=%TPATH ;;RESTORE ORIGINAL PATH | | RETURN ;;RETURN TO CALLER RETURN ;;RETURN TO CALLER | | | | . | | . | | | | [F1] WINDOWS ;;TITLE LINE AND SWITCHES | | CDD C:\WINDOWS\FILES ;;CHANGE DRIVE & DIRECTORIES | | GOSUB SETWINPATH ;;SET PATH FOR WINDOWS | | WIN%XM ;;RUN WINDOWS & SWAP OUT DCOM | | GOSUB RMVWINPATH ;;REMOVE PATH CHANGES | | CD C:\ ;;CHANGE C: BACK TO ROOT DIR | | CDDO ;;RETURN TO ORIG DRIVE & DIR | | | | . | | . | | | | `---------------------------------------------------------------------' In the example above two special definitions are used, [MENUAUTO] and [PUBLIC]. While this might be a good example of how to run Windows in a dCOM macro key, its primary intent is to indicate how to use special definitions. 18 Macro Key Definitions - Special ---------------------------------------------------------------------- [FILEAUTO][FILEAUTO] A [FILEAUTO] definition executes once, immediately after the macro file is loaded, irregardless of whether the menu mode is active. If a macro file calls another macro file, when control returns to the original macro file the [FILEAUTO] definition will re-execute. Normally you would not use a RETURN statement to end a [FILEAUTO] definition, unless the entire purpose of the macro file is to be a [FILEAUTO] definition (acting as a significant subroutine or program) and you then want control to return to a calling macro file. If you develop some macro code that does some serious processing, it may be easier to write it all in a separate macro file under a [FILEAUTO] definition. This allows your macro code to be called and executed simply by using a GOSUBMF command in the active macro file. The advantages are that its simpler to initially install, and also easier to circulate updated versions, especially on someone else's computer. The location of a [FILEAUTO] definition can be anywhere in a macro file. Logically though, it would probably make more sense to have it near the start. Labels within a [FILEAUTO] definition can be referred to by external macro definitions by using a syntax of "FA:label" (i.e. GOSUB FA:LABEL1). 19 Macro Key Definitions - Special ---------------------------------------------------------------------- [MENUAUTO][MENUAUTO] A [MENUAUTO] definition only executes if the menu mode is active, and does so immediately before the menu is about to be displayed - each and every time. The original intent of the [MENUAUTO] definition was to provide a means to alter the appearance of the menu mode, but that's not to say you can't use the opportunity to execute other macro code. The location of a [MENUAUTO] definition can be anywhere in a macro file. Logically though, it would probably make more sense to have it near the start. An example of [MENUAUTO] is: ,---------------------------------------------------------------------, MAIN MACRO'S ;;MENU TITLE | | | | [MENUAUTO] ;;RUNS BEFORE MENU DISPLAYS | | CLS 0,1,176 ;;CLS IN BLACK ON BLUE w/'░' | | WINDOW 1,1,4,80,1,7,1,1 ;;DISPLAY A BOX ON THE SCREEN | | ;; AND THEN DISPLAY VER INFO | | ECHO dCOM Menu System Ver %SS(%DV,1,1).%SS(%DV,2,2); | | CPOSN ,78 ;;POSITION TO RIGHT EDGE | | ;; & DISPLAY DATE & TIME | | ECHOR %DW, %MY %SS(%DT,4,2), 19%SS(%DT,7,2) %TI; | | CLOCK %CL,%CC-8 ;;TURN CLOCK ON | | CPOSN 3,3 ;;MOVE CURSOR TO NEXT LINE | | ECHO Current User %LN; ;;DISPLAY USER NAME | | CPOSN ,78 ;;POSITION TO RIGHT EDGE | | ;; & DISPLAY FREE DISK SPACE | | ECHOR %FC(%FD(C)) Free of %FC(%TD(C)) On Drive C: | | RSTWIN /N ;;FREE WINDOW, LEAVE SCREEN | | MENUSTART 8,14 ;;SET MENU DISPLAY POSITION | | MENUCOLOR 0,3,1,14,2 ;;SET MENU COLORS/BORDER TYPE | | | | [F1] MS-WORD ;;TITLE LINE AND SWITCHES | | CDD C:\MSWORD ;;CHANGE DRIVE & DIRECTORIES | | WORD ;;RUN MS-WORD | | CD C:\ ;;CHANGE C: BACK TO ROOT DIR | | CDDO ;;RETURN TO ORIG DRIVE & DIR | | | | . | | . | | | | `---------------------------------------------------------------------' 20 Macro Key Definitions - Special ---------------------------------------------------------------------- The example above uses the author's favorite color scheme. Another popular set of colors can be had by substituting the CLS, WINDOW, and MENUCOLOR commands with these: CLS 3,1,176 WINDOW 1,1,4,80,1,3,1,1 MENUCOLOR 15,1,11,14,2 Labels within a [MENUAUTO] definition can be referred to by external macro definitions by using a syntax of "MA:label" (i.e. GOSUB MA:LABEL1). [DRIVEAUTO][DRIVEAUTO] A [DRIVEAUTO] definition automatically executes every time the default drive is changed. Don't ask me what the proposed usefulness is, it was implemented as part of a deal with another user who wanted it. Labels within a [DRIVEAUTO] definition can be referred to by external macro definitions by using a syntax of "DA:label" (i.e. GOSUB DA:LABEL1). [PUBLIC][PUBLIC] Using a [PUBLIC] definition provides a way to group common subroutines under one definition. Labels used under a [PUBLIC] definition are available to all definitions in a macro file. If the same label name is defined both in a [PUBLIC] definition and locally, the local definition's label will be used. Label names defined under any other type of definition are normally private to that definition. This allows labels of the same name to exist in several definitions without causing a conflict. It is possible though to call a label in a different definition by preceding the label's name with the name of the external definition (i.e. GOSUB F1:MYPROC). But this method of calling external subroutines could soon become awkward. A [PUBLIC] definition can be defined more than once in a macro file. If it is, subsequent occurrences are simply appended to the currently built definition. This could be useful if you have some public routines in a separate file linked in with an INCLUDE command, but still want to have some public routines which are written in the local macro file. An example of using the [PUBLIC] definition is shown at the start of this section on page 18. 21 Macro Key Definitions - Special ---------------------------------------------------------------------- [EQUATES][EQUATES] Unlike other types of macro definitions, an [EQUATES] definition does not contain executable macro code, it defines static user variables. These are actually not variables though, they are more like aliases. But for our purposes we'll call them equate variables. These are variables that cannot be changed once they are defined. Their purpose is to allow something that might be changed frequently to be expressed only once, making it easy to change by not having to search the entire macro file for all occurrences of the literal text. Equate variables must start with a "%$" sequence. After that, they must follow the rules of regular variable names which can only contain the letters A-Z, 0-9, and the underscore. Equate variables are actually resolved and expanded during compilation, not during runtime. Therefore, unlike regular user variables, the size of their name has no affect on memory usage. But the size of their value does, because the load (runtime) image will contain a copy of their value in every occurrence in which they were used. Equate variables currently cannot use another equate variable as part of their value. An [EQUATE] definition can be defined more than once in a macro file. If it is, subsequent occurrences are simply appended to the currently built variable list. A simplistic example of using [EQUATES] is: ,---------------------------------------------------------------------, MAIN MACRO'S ;;MENU TITLE | | | | [EQUATES] ;;START OF EQUATE VARIABLES | | %$WORD_DIR=C:\MSWORD ;; SET %$WORD_DIR VARIABLE | | %$WINDOWS_DIR=C:\WINDOWS ;; SET %$WINDOWS_DIR VARIABLE | | | | [F1] MS-WORD ;;TITLE LINE AND SWITCHES | | CDD %$WORD_DIR ;;CHANGE DRIVE & DIRECTORIES | | WORD ;;RUN MS-WORD | | CDDO ;;RETURN TO ORIG DRIVE & DIR | | | | . | | . | | | | `---------------------------------------------------------------------' 22 ====================================================================== MACRO LANGUAGEMACRO LANGUAGE ====================================================================== 23 Macro Language - Overview ---------------------------------------------------------------------- Macro Language OverviewMacro Language Overview The macro language is a set of commands that the macro engine directly recognizes and executes. While in some ways it may seem like an interpreted language, it really isn't. The ASCII macro files are automatically compiled and tokenized on-the-fly when they have been modified. The main purpose for automatically compiling a macro file is to resolve which commands are macro commands, and translate them to a unique internal code (token) that allows the macro engine to immediately know what the commands are when it executes the macro file. When a command is used that's not part of the macro language, the macro compiler assumes its an external program. Before making this assumption however, it scans the command against a list of internal MS-DOS commands. If the command matches an internal MS-DOS command (i.e. TIME, COPY, etc...), a second copy of COMMAND.COM is used when that macro line is executed. When a program is run directly by the macro engine, all forms of redirection are supported except piping. If piping is used, the macro engine automatically uses a second copy of COMMAND.COM to run the program instead of running the program directly. In the event that one of the macro commands happens to coincide with the name of an external program, and you want the external program to run, not the macro command - start the macro line with a ">" to force the macro engine to use a second copy of COMMAND.COM to run the program which keeps the macro engine from mistakenly executing the internal macro command. (Another way to prevent this from happening is to spell out the entire path to the program.) White space (which are space or tab characters) found before a command or after all of its parameters is ignored for memory conservation. White space imbedded between a command and its parameters is also ignored. The only time when this might prove to be a problem is if you use one of the ECHO commands and want to display leading or trailing spaces. To work around this, enclose the text within double quotation marks. Comments may be specified at any place in a macro line by using two semicolons in sequence ("; ;"). When a comment is encountered, the rest of the line is ignored and consumes no memory. White space leading up to the comment is also ignored. 24 Macro Language - Overview ---------------------------------------------------------------------- If a comment starts at the beginning of a line, a single semicolon is all that is needed to start the comment. Using two semicolon's will have no adverse affect however. The macro language is almost 100% batch file compatible. You should be able to directly import most of your existing batch files, precede it with a title line, and then execute it. What all this means is that there's a lot of sophisiticated intelligence going on behind the scene to make the macro system as flexible and easy to use as possible, but yet still keep it a responsive 'slick-tight' and efficient runtime environment. A lot of other menu systems and shells employ various forms of trickery and tom-foolery by trying to fool COMMAND.COM with temporary batch files. In dCOM's macro system, when you say run this program, dCOM runs that program. When you say delete these files, dCOM deletes those files. And its darn quick about doing it.... 25 Macro Language - IF Statements ---------------------------------------------------------------------- IF StatementsIF Statements IF commands are expressed as either a block-type structure or as a single line statement. If the key word "THEN" is used as the command portion of an IF statement, it is considered a block-type IF command. If there is no command portion following the IF expression, it too will be considered a block-type IF structure. The single line version only executes its command portion when the IF expression is true. Execution of the line following a single line IF statement is not subject to the IF condition and will always execute unless the IF command jumps around it with a GOTO instruction. Examples of single line IF statements are: IFIF %EL>0 GOTO ERROR IFIF EXIST *.BAK DEL *.BAK Block-type IF statements allow multiple lines to execute if the expression is true, or multiple lines to execute if the expression is false (by using an ELSE command). For example: IFIF %EL>0 THENTHEN BEEP ECHO An Error Occurred ELSEELSE ECHO No Error Occurred ENDIFENDIF Within a block-type IF structure, an ELSEIF may also be used to further the test if the first expression is false. For example: IFIF 2>3 THENTHEN ECHO New Math - Two is Greater Than Three ELSEIFELSEIF 3>2 THENTHEN ECHO Three is Greater Than Two ELSEELSE ECHO No IF Comparisons Are True ENDIFENDIF You can nest block IF statements with no logical limit. But, for each IF..THEN combination there must be a matching ENDIF. 26 Macro Language - IF Statements ---------------------------------------------------------------------- Compound ExpressionsCompound Expressions IF expressions can be joined using .AND. and .OR. logical operators. There is no limit on how many .AND. or .OR. operators you can use to tie multiple IF expressions together other than the macro engine's internal line length limit of 512 characters. When IF expressions are tied together with logical .AND. or .OR. operators, each individual expression can fully utilize all possible IF statement options (e.g. EOF(#), ERRORLEVEL, EXIST, NOT, etc...). Spaces used around .AND. or .OR. operators are not required, but are recommended to reduce any possible ambiguities. There is no method of expressing a hierarchy to change the order of evaluating the expressions used. Compound IF expressions are evaluated from left to right, and the result accumulated from left to right. For example: IFIF 2>3 .OR. 5>6 THENTHEN ECHO Either 2 is greater than 3, or 5 is greater than 6?? ELSEIFELSEIF 3>2 .AND. 6>5 THENTHEN ECHO Both 3 is greater than 2, and 6 is greater than 5!! ELSEELSE ECHO No IF Comparisons Are True ENDIFENDIF 27 Macro Language - In-Line Arithmetic ---------------------------------------------------------------------- In-Line ArithmeticIn-Line Arithmetic Any macro command that expects a numeric parameter, will recognize the use of in-line arithmetic within the parameter. Even IF statements will use in-line arithmetic if both operands of the expression are totally comprised of numeric characters. ,---------------------------------------------------------------------, NOTE: IF expressions are very sensitive to the use of space | | characters. If you use in-line arithmetic in an IF | | expression, don't use space characters between math operators | | or the IF expression will probably improperly determine the | | start of the command portion. | | `---------------------------------------------------------------------' For example, the CPOSN command (which moves the cursor) normally expects its arguments for the line and column to be numbers. Therefore, you can use a statement like "CPOSN ,%CC+10" and advance the cursor column 10 characters to the right. In-line arithmetic only recognizes the four basic math operators (+, - , *, and /). It also correctly handles signed operands (i.e. 2/-3). Multiple operations can be expressed subject only to the internal line limit of the macro engine (i.e. 1+2+3+4). There is no method of controlling the order of evaluation. In-line math is always parsed and accumulated on a left to right basis, with the result of each operation working against that from the one before. Since there is no method to override the order of evaluation (parenthesis, if used, will only cause parsing to determine nothing numeric is going on here), the normal algebraic rules of performing multiplication and division before addition and subtraction are also ignored. Macro commands which accept parameters that can be either text or numeric will not recognize in-line arithmetic. It would be too unreliable to try to do so. 28 Macro Language - Menus and Windows ---------------------------------------------------------------------- Macro Menus and WindowsMacro Menus and Windows A number of the macro commands display information using pop-up windows: APPMENU, MENU, QFORMAT, SELECT, WINDOW, etc... When these commands are used, if the macro key has done nothing to force the screen to be cleared (no ECHO commands used or programs run), these commands will overlay whatever is on the screen (except the WINDOW command which always clears the screen first if it hasn't been cleared yet). If the file handler was active when the macro is run, the menu will pop-up using bold colors. If the menu mode was active and its screen is still fresh, these commands will display using the menu mode's colors. If the screen had been cleared by a preceding macro command, the menu will display using the current CGA colors dCOM is configured for (if you are using the EGA palette, you will have to temporarily disable it in the file handler's configuration menu to see what the CGA colors are), unless the menu's colors have been overridden beforehand with a MENUCOLOR command. All of the menuing-type commands (everything except WINDOW), are mouse-sensitive. Clicking the mouse left button on the desired selection acts as if Return was pressed on it. Clicking the mouse right button acts as if Escape were pressed. The pop-up menu's are also temporarily moveable by holding the shift key down while using an appropriate arrow key. All of the menuing-type commands also have a special memory feature. While the macro system is acting as a menu (either because the menu mode is active, or the file handler's Backspace overlay is kept alive), if any of these menuing-type commands are re-executed, they will initially start up with the option highlighted that was last used (unless a switch overrides the default option initially selected). Each of the menuing-type macro commands recognizes a standard set of switches which can further customize the menu by doing such things as overriding where the menu is displayed, override the starting selection, etc.... These switches are described on the following page. 29 Macro Language - Menuing Switches ---------------------------------------------------------------------- Menuing SwitchesMenuing Switches All of the menuing-type macro commands (APPMENU, MENU, QFORMAT, and SELECT) recognize a standard set of switches (in addition to any that may be unique to a particular command) which can be used to further customize the menu's appearance. Switches which are common to one or more of the menuing-type macro commands are defined here. Switches that are unique to a particular macro command are defined under that command. /C=lin,col/C=lin,col Menus are normally displayed centered on the middle of the screen. This switch overrides where a menu is physically displayed by centering it on the line and column coordinates provided (i.e. /C=10,21). The menu's display position will automatically self-adjust in the appropriate direction if any portion of the menu would end up off the screen using the coordinates specified. /E=n/E=n Overrides the maximum entries per column. Menus will normally display up to 15 entries in a column before starting additional columns. This switch allows you to reduce or expand that number (i.e. /E=10). /F=text/F=text Overrides the default selection initially highlighted based on finding the selection that matches the text specified (i.e. /F=Option3). /L=lin,col/L=lin,col Menus are normally displayed centered on the middle of the screen. This switch overrides where a menu is physically displayed by locating the menu's top left corner on the line and column coordinates provided (i.e. /L=2,3). The menu's display position will automatically self-adjust in the appropriate direction if any portion of the menu would end up off the screen using the coordinates specified. /R/R This switch causes a menu to remain on the screen after a selection is made, with its window still saved on the windowing stack. A RSTWIN macro command is then used at some point later on to restore the screen and remove the window, and also to restore the windowing stack. This switch allows menu's to overlay each other. Care should be exercised though to ensure that a matching RSTWIN will occur for each menu kept alive with /R, under all possible paths of macro execution. /S=n/S=n Overrides the default selection initially highlighted based on the desired selection's order in the menu (i.e. /S=3). 30 Macro Language - Macro Commands ---------------------------------------------------------------------- Macro CommandsMacro Commands label.............32 MKDIR.............56 >command..........32 MENU..............56 ADD...............33 MENUCOLOR.........58 APPMENU...........33 MENUSTART.........59 BEEP..............34 MENUTITLE.........59 BROWSE............34 MUL...............60 CD................35 ONBREAKGOTO.......60 CHDIR.............35 ONERRORGOTO.......61 CDD...............35 OPEN..............62 CDDO..............35 PATH..............63 CLOSE.............35 PATHADD...........63 CLS...............36 PATHDEL...........64 COLOR.............36 PAUSE.............65 CREATE............37 PRINTFIL..........65 DEL...............37 PRINTSTR..........65 ERASE.............37 PROMPT............66 DELAY.............38 QFORMAT...........66 DELAYW............38 RD................67 DIV...............39 RMDIR.............67 DO................39 READ..............67 DO WHILE..........40 READB.............67 ECHO..............41 READLN............68 ECHOC.............41 REBOOT............68 ECHOR.............42 RECOMPILE.........69 EDIT..............42 REM...............69 ELSE..............42 RETURN............69 ELSEIF............42 RSTWIN............70 ENDDO.............43 RUNMACRO..........70 ENDIF.............43 SELECT............70 EXIT..............43 SET...............73 EXITDCOM..........43 SHIP..............73 GET...............44 SUB...............74 GETW..............45 VLIST.............74 GOSUB.............46 WINDOW............74 GOSUBMF...........47 WRITE.............76 GOTO..............49 WRITEB............76 GOTOMF............49 IF................50 IF EOF............51 IF ERRORLEVEL.....52 IF EXIST..........52 INCLUDE...........53 KEYBOARD..........54 KEYWAIT...........54 LOOP..............55 MACROMENU.........55 MD................56 31 Macro Language - Macro Command Reference ---------------------------------------------------------------------- Macro Command ReferenceMacro Command Reference ,---------------------------------------------------------------------, d:d: | | `---------------------------------------------------------------------' Sets a new default drive (i.e. "A:", or "C:"). See also: %DD, %OD ,---------------------------------------------------------------------, :label:label | | `---------------------------------------------------------------------' Designates a label or comment. Any line beginning with a colon is considered a label. Labels are used to specify the target of GOSUB, GOTO, LOOP, and other macro commands. Label lines themselves are not executed. When you enter a label's text as part of a GOSUB, GOTO, or LOOP command, do not include the colon - just the text following the colon. Labels may contain imbedded spaces with no ill effect and are case insensitive. Labels will be resolved by the macro compiler instead of during runtime, if the text of the label is 3 characters or longer and doesn't use a macro variable. The reason why 3 characters is that the compiler internally replaces the label with its resolved line number, and it takes 3 bytes to hold the information. This can have a significant impact on execution speed in large macro definitions by saving the macro engine from having to search for the label each time a branching instruction is encountered. Bottom line is, if you can remember, try and make the text of your labels at least 3 characters long. This command behaves identically with its MS-DOS batch file counterpart. See also: GOTO, GOSUB, LOOP, ONBREAKGOTO, ONERRORGOTO ,---------------------------------------------------------------------, >command>command | | `---------------------------------------------------------------------' Forces a macro command to be passed to a second copy of COMMAND.COM. Precede macro lines with a ">" if a desired program's name happens to coincide with the same name as one of the macro commands, or if 32 Macro Language - Macro Command Reference ---------------------------------------------------------------------- the command needs to be processed by the native command processor (like 4DOS). ,---------------------------------------------------------------------, ADDADD destination,source | | `---------------------------------------------------------------------' Performs a 32-bit signed integer add operation using the two operands. The destination operand must be a user variable. The source operand can be a combination of literal text and/or macro variables. The source operand can also include in-line arithmetic, which is evaluated from left to right without regard for standard algebraic order (i.e. multiplication before addition). The result of the operation is returned in the destination user variable. See also: SUB, MUL, DIV Examples: %VAR1=12 ;;%VAR1 = 12 %VAR2=23 ;;%VAR2 = 23 ADD %VAR1,1 ;;%VAR1 = 13 (12+1) ADD %VAR1,%VAR2 ;;%VAR1 = 36 (13+23) ADD %VAR1,%VAR2+3*2 ;;%VAR1 = 88 (36+((23+3)*2)) ,---------------------------------------------------------------------, APPMENUAPPMENU filename | | `---------------------------------------------------------------------' Displays an applications menu. This feature allows a menu of different applications (programs) to be quickly displayed. The menu is defined by an applications menu text file found in dCOM's home directory. Applications menu text files must have a .APP extension. This feature is similar to the file handler's '*' - Applications Menu command except that a filename must be provided as an argument. If the menu is cancelled with the Escape key or mouse right button, macro execution aborts unless trapped with ONBREAKGOTO. This command also recognizes the menuing-type switches described on page 30. The format of an applications menu text file is: 33 Macro Language - Macro Command Reference ---------------------------------------------------------------------- menutitle menutext,[changepath],[path]program parameters menutext,[changepath],[path]program parameters * * menutext,[changepath],[path]program parameters Tabs may be used instead of commas to delimit fields. Two commas in sequence must be used though if the changepath field is not given. "menutitle" is the text you want displayed as the menu's title. "menutext" is the name for the option that shows in the menu. "changepath" is the pathspec to change to before running the program. "program" is the name of the executable program, followed by its parameters. When an application is run from this menu the default drive and current directory are saved before executing the program, and restored when it exits. See also: MENUCOLOR ,---------------------------------------------------------------------, BEEPBEEP [ansimusic] | | `---------------------------------------------------------------------' Beeps the speaker This command is also capable of playing ANSI music. For more information refer to the appendix describing ANSI music on page 140. ,---------------------------------------------------------------------, BROWSEBROWSE [d:][path]filename | | `---------------------------------------------------------------------' Provides access to dCOM's text file browser from inside a macro key. When this command is used, dCOM will attempt to save the entire screen to the windowing stack before invoking the browser. If it was successfully saved, the entire screen is restored when the browser exits. See also: EDIT 34 Macro Language - Macro Command Reference ---------------------------------------------------------------------- ,---------------------------------------------------------------------, CDCD [d:]path | | CHDIRCHDIR [d:]path | | `---------------------------------------------------------------------' Changes the current directory. If no drive is given, the default drive is assumed. This command behaves identically with its MS-DOS counterpart. See also: CDD, CDDO, %CD, %OS ,---------------------------------------------------------------------, CDDCDD [d:][path] | | `---------------------------------------------------------------------' Changes both the default drive and its current directory. This command is provided as a shortcut to having to use two lines to change drives and subdirectories before running a program, etc.... See also: CD, CDDO, %CD, %DD, %OD, %OS ,---------------------------------------------------------------------, CDDOCDDO | | `---------------------------------------------------------------------' Changes back to what was the default drive and its current directory when the macro key was originally executed. Even though the logical use of this command would be on the end of a macro key, the use of this command is purely optional and can occur more than once as desired. See also: CD, CDD, %OD, %OS ,---------------------------------------------------------------------, CLOSECLOSE [[#]filenumber] | | `---------------------------------------------------------------------' Closes a file number, or all open file numbers if no parameters are specified. Files are opened with either the OPEN or CREATE macro commands. They are automatically closed when macro execution terminates, even if they haven't been explicitly closed with this command. See also: CREATE, OPEN 35 Macro Language - Macro Command Reference ---------------------------------------------------------------------- Example: OPEN #1,C:\CONFIG.SYS ;;OPEN C:\CONFIG.SYS DO WHILE NOT EOF (1) ;;DO WHILE NOT END OF FILE READLN #1,%TEXT ;; READ NEXT LINE ECHO %TEXT ;; DISPLAY IT ENDDO ;;END OF DO BLOCK CLOSE #1 ;;CLOSE THE FILE ,---------------------------------------------------------------------, CLSCLS [foreground][,background][,fillchar] | | `---------------------------------------------------------------------' Clears the screen and homes the cursor. If no colors are given, the screen is cleared using the active colors set with a COLOR command. If no COLOR command is active, the screen is cleared using an ANSI instruction if ANSI.SYS is loaded, otherwise a BIOS call is used. The optional "fillchar" provides a means to clear the screen with a character other than spaces. It is specified as an ASCII character code. See also: COLOR Example: CLS 0,1,176 ;;CLS IN BLACK ON BLUE USING '░' ,---------------------------------------------------------------------, COLORCOLOR [foreground][,background] [/b][/i][/r][/u][/x] | | `---------------------------------------------------------------------' Sets the color used for subsequent CLS and ECHO commands. When a COLOR command is active, the macro engine uses dCOM's internal screen driver to perform screen writes. (The internal driver is also used when a WINDOW is open on the screen.) The internal screen driver is much faster than using MS-DOS calls to write to the screen. Using a COLOR command without any arguments resets the use of color and causes the macro engine to start using DOS calls again to perform screen writes (as long as a WINDOW isn't active). 36 Macro Language - Macro Command Reference ---------------------------------------------------------------------- Optional Switches: /B/B Sets the blinking attribute. /I/I Sets the high intensity attribute. /R/R Reverses the active colors. Using this switch is the only method to achieve reverse video on a monochrome video cards (color changes are effectively ignored). /U/U Sets the underline attribute. This attribute only works on monochrome video cards. /X/X Removes all attributes. This switch is reacted to first before any other attribute switches, despite the order in which they might be given. See also: MENUCOLOR Example: COLOR 1,3 ;;SET ACTIVE COLOR TO BLU ON CYN COLOR 7,0/R ;;SET WHT ON BLK, AND REVERSE IT COLOR /X/I ;;RESET ATRIBS, THEN SET INTENSE ,---------------------------------------------------------------------, CREATECREATE [#]filenumber,[d:][path]filename | | `---------------------------------------------------------------------' Creates a file for writing and associates it with a file number. If the file already exists, its previous contents are erased. Refer to the OPEN command for more details on the file I/O system. See also: OPEN, WRITE, CLOSE Example: CREATE #1,C:\TEMPDAT.TXT ;;CREATE C:\TEMPDAT.TXT ,---------------------------------------------------------------------, DELDEL [d:][path]filename [/h][/n][/r][/s][/v] | | ERASEERASE [d:][path]filename [/h][/n][/r][/s][/v] | | `---------------------------------------------------------------------' Deletes files. The filename may include wildcards. For the most part this command behaves like its MS-DOS counterpart, except that no confirmation prompt is displayed when a "*.*" mask is used. 37 Macro Language - Macro Command Reference ---------------------------------------------------------------------- Optional Switches: /H/H Allows files flagged as hidden to be deleted. /N/N Suppresses any macro error messages like "No Matching files", or "Access Denied". This switch could be used in unattended modes to ensure macro execution will always continue. It also provides an easy way to do something like "DEL *.BAK/N" on the tail-end of a macro that runs something which produces .BAK files, without having to worry about doing an IF EXIST first to avoid error messages if none are found. /R/R Deletes files flagged as read-only instead of producing an "Access Denied" error message. /S/S Allows files with the system attribute to be deleted. /V/V Causes a verbose display of each file deleted. ,---------------------------------------------------------------------, DELAYDELAY [seconds] [/v] | | `---------------------------------------------------------------------' Causes the macro to pause for the time period specified in seconds. If the seconds aren't provided, a delay of 1 second will be used. Pressing Escape or Ctrl-C while the delay period is active will cause the macro to abort unless trapped with an ONBREAKGOTO. Pressing any other key will cancel the delay countdown and macro execution continues. Optional Switches: /V/V Causes a verbose display of the delay countdown. See also: DELAYW ,---------------------------------------------------------------------, DELAYDELAYW [seconds] | | `---------------------------------------------------------------------' This is a windowized version of DELAY. It too causes the macro to pause for the time period specified in seconds. If the seconds aren't provided, a delay of 1 second will be used. But it also pops up a window that displays the countdown, and then removes the window when the countdown is finished. Pressing Escape or Ctrl-C while the delay period is active will cause the macro to abort unless trapped with an ONBREAKGOTO. Pressing any other key will cancel the delay countdown and macro execution continues. 38 Macro Language - Macro Command Reference ---------------------------------------------------------------------- This command also recognizes the menuing-type switches described on page 30. See also: DELAY ,---------------------------------------------------------------------, DIVDIV destination,source | | `---------------------------------------------------------------------' Performs a 32-bit signed integer divide operation using the two operands. The destination operand must be a user variable. The source operand can be a combination of literal text and/or macro variables. The source operand can also include in-line arithmetic, which is evaluated from left to right without regard for standard algebraic order (i.e. multiplication before addition). The result of the operation is returned in the destination user variable. See also: ADD, SUB, MUL Examples: %VAR1=57 ;;%VAR1 = 57 %VAR2=3 ;;%VAR2 = 3 DIV %VAR1,2 ;;%VAR1 = 28 (57/2) DIV %VAR1,%VAR2 ;;%VAR1 = 9 (28/3) DIV %VAR1,%VAR2+4/2 ;;%VAR1 = 3 (9/((3+4)/2)) ,---------------------------------------------------------------------, DODO [d:][path]mask [/d][/h] | | `---------------------------------------------------------------------' Repeatedly executes a block of macro lines following the DO command, up to a matching ENDDO, for each occurrence of a file found with the mask specified. Within a DO block, the %DN and %DE variables are used to access the current iteration's filename, or filename and extension (respectively). The %DS variable can also be used to access the current iteration's file size. If no files qualify with the mask specified, execution jumps immediately around the DO block. Combinations of DO and DO WHILE blocks are nestable up to 16 levels deep. 39 Macro Language - Macro Command Reference ---------------------------------------------------------------------- Optional Switches: /D/D Causes the DO command to search for subdirectory names instead of filenames. /H/H Causes hidden files (or subdirectories) to be included as well. See also: DO WHILE, ENDDO, %DN, %DE, %DS Example: [F1] CONV .ARC TO .ZIP ;;TITLE LINE AND SWITCHES MD C:\TEMPDIR ;;MAKE A TEMPORARY DIRECTORY DODO *.ARC ;;START OF DO BLOCK PKUNPAK %DE%DE C:\TEMPDIR ;; UNARCHIVE CURRENT DO FILE DEL %DE%DE ;; DELETE CURRENT DO FILE PKZIP -m %DN%DN C:\TEMPDIR\*.* ;; REZIP (MOVE) TO DO FILE ENDDOENDDO ;;END OF DO BLOCK RD C:\TEMPDIR ;;REMOVE TEMPORARY DIRECTORY ,---------------------------------------------------------------------, DO WHILEDO WHILE expression | | `---------------------------------------------------------------------' Repeatedly executes a block of macro lines following the DO command, up to a matching ENDDO, for as long as the expression is true. Any valid IF construct can be used as the DO WHILE expression, including .AND. and .OR. logical operators. If the expression is initially false, execution jumps immediately around the DO WHILE block. Combinations of DO and DO WHILE blocks are nestable up to 16 levels deep. See also: DO, ENDDO 40 Macro Language - Macro Command Reference ---------------------------------------------------------------------- Examples: OPEN #1,C:\CONFIG.SYS ;;OPEN C:\CONFIG.SYS DO WHILE NOT EOF (1) ;;WHILE NOT END OF FILE READLN #1,%TEXT ;; %TEXT = NEXT LINE ECHO %TEXT ;; DISPLAY IT ENDDO ;;END OF DO WHILE BLOCK %COUNT=0 ;;RESET COUNTER DO WHILE %COUNT<25 .AND. %KB<>%(27) ;;WHILE CNT<25 AND NO ESC ADD %COUNT,1 ;; INCREMENT COUNTER ECHO %COUNT ;; DISPLAY IT ENDDO ;;END OF DO WHILE BLOCK ,---------------------------------------------------------------------, ECHOECHO ["]text["][;] | | `---------------------------------------------------------------------' Echo's (displays) text to the screen starting at the current cursor position. A carriage return and line feed are automatically appended to the text unless the text ends with a semi-colon (which isn't displayed). To display leading or trailing spaces, surround the text in optional double quotation marks. The ECHO command internally supports redirection using the ">", ">>", and "<" operators. In order to provide batch file interchangeability, ECHO ON and ECHO OFF commands are ignored. If you actually want to display the text "ON" or "OFF", enclose the text portion in quotation marks. See also: COLOR, ECHOC, ECHOR ,---------------------------------------------------------------------, ECHOCECHOC text[;] | | `---------------------------------------------------------------------' Echo's (displays) text to the screen, centered on the current cursor position. ECHOC behaves the same as ECHO except that it doesn't support redirection The normal use of ECHOC is to first position the cursor on the column where you want the text centered, and then use ECHOC. See also: COLOR, ECHO, ECHOR 41 Macro Language - Macro Command Reference ---------------------------------------------------------------------- ,---------------------------------------------------------------------, ECHORECHOR text[;] | | `---------------------------------------------------------------------' Echo's (displays) text to the screen right justified at the current cursor position. ECHOR behaves the same as ECHO except that it doesn't support redirection The normal use of ECHOR is to first position the cursor on the column where you want the right-most edge of the text to appear, and then use ECHOR. See also: COLOR, ECHO, ECHOC ,---------------------------------------------------------------------, EDITEDIT [d:][path]filename | | `---------------------------------------------------------------------' Provides access to dCOM's text editor from inside a macro key. If a complete path is not provided, the editor will resolve it so that the editor can be exited with Alt-Q, directories changed, and a return to the editor with a subsequent save command won't loose track of where the file was originally read from. When this command is used, dCOM will attempt to save the entire screen to the windowing stack before invoking the text editor. If it was successfully saved, the entire screen is restored when the text editor exits. See also: BROWSE ,---------------------------------------------------------------------, ELSEELSE | | ELSEIFELSEIF expression [THENTHEN] | | `---------------------------------------------------------------------' Divides an IF block into separate sections. The first section executes if the IF comparison is true, the section following an ELSE statement executes if the IF comparison is false. If the ELSEIF statement is used, a second comparison is performed and its section executed, if the first IF expression is false and the ELSEIF expression is true. Use of the keyword THEN is optional. ELSEIF statements can only be used in block-type IF constructs and they recognize all options and variations available with an IF statement. For more information refer to IF Statements on page 26. 42 Macro Language - Macro Command Reference ---------------------------------------------------------------------- See also: IF, ENDIF ,---------------------------------------------------------------------, ENDDOENDDO | | `---------------------------------------------------------------------' Specifies the end of a DO or DO WHILE block. See also: DO, DO WHILE ,---------------------------------------------------------------------, ENDIFENDIF | | `---------------------------------------------------------------------' Specifies the end of an IF block. See also: IF ,---------------------------------------------------------------------, EXITEXIT | | `---------------------------------------------------------------------' Terminates execution of a macro definition. ,---------------------------------------------------------------------, EXITDCOMEXITDCOM [errorlevel] [/n] | | `---------------------------------------------------------------------' Causes dCOM to exit back to the previous process. If no errorlevel is provided, dCOM will exit with an errorlevel of 0 (the same as when dCOM exits with the file handler's "X" command). Using the EXITDCOM command with an errorlevel allows you to use a batch file to run dCOM and then test on the errorlevel returned when dCOM exits. 43 Macro Language - Macro Command Reference ---------------------------------------------------------------------- Optional Switches: /N/N Suppresses any error messages which might be displayed before actually exiting (i.e. Spooler Not Empty, TSR's Will Be Removed, etc...). This switch should be used if you are using the EXITDCOM command in conjunction with a KEYBOARD command, because if the EXITDCOM command displays a warning message before exiting, it will "eat" any keystrokes stuffed in the keyboard queue. Example: [F1] AUTOCAD ;;TITLE LINE AND SWITCHES EXITDCOM 100 ;;EXIT DCOM WITH ERRORLEVEL 100 [F2] HARVARD PROJ MGR ;;TITLE LINE AND SWITCHES EXITDCOM 101 ;;EXIT DCOM W/NO EXIT PROMPTS . . --[DCOM.BAT]---------------------------------------------------- :START DCOM /M IF ERRORLEVEL 255 GOTO EXIT IF ERRORLEVEL 101 GOTO HTPM IF ERRORLEVEL 100 GOTO ACAD GOTO EXIT :HTPM C: CD \HTPM HTPM GOTO START :ACAD C: CD \ACAD ACAD GOTO START :EXIT The first part of this example are macro keys that exit dCOM with various error levels. The second part is a batch file that runs dCOM and then looks for those errorlevels when dCOM exits. When you test for errorlevels in a batch file, they must be tested in descending order. ,---------------------------------------------------------------------, GETGET var[,prompt] | | `---------------------------------------------------------------------' Gets a response from the keyboard into a user variable, optionally displaying a prompt first. 44 Macro Language - Macro Command Reference ---------------------------------------------------------------------- If the prompt is cancelled with the Escape key, macro execution aborts unless trapped with ONBREAKGOTO. See also: GETW Example: [F1] ZIP TAGGED FILES ;;TITLE LINE AND SWITCHES GETGET %FILE Enter Zip File: ;;GET .ZIP FILENAME IN %FILE :LABEL1 ;;LABEL FOR LOOP JUMP ECHO Arcing %TE to %FILE ;; DISPLAY CURRENT LOOP FILE PKZIP -ex %FILE %TE >NUL ;; ADD IT TO .ZIP FILE LOOP LABEL1 ;;LOOP THROUGH TAGGED FILES ,---------------------------------------------------------------------, GETWGETW var,length[,prompt] [/p] | | `---------------------------------------------------------------------' This is a windowized version of GET. It too gets a response from the keyboard into a user variable, but it does so inside a box that pops-up in the center of the screen, irrespective of the current cursor position. The "length" parameter is the editing length you want to provide (so it can build an appropriately sized box). If the user variable being edited already has a value, the value will initially be displayed as the default value for the prompt. If the prompt is cancelled with the Escape key, macro execution aborts unless trapped with ONBREAKGOTO. Optional Switches: /P/P Invokes the password mode. Default text, or text typed, with this mode active causes characters to be displayed as dots instead of the actual characters. See also: GET Example: %FILE=TESTFILE.TXT ;;SET DEFAULT RESPONSE GETWGETW %FILE 10 Enter Filename: ;;GET A FILENAME IN %FILE Would produce: ,----------------------------, | Enter Filename: _ | `----------------------------' 45 Macro Language - Macro Command Reference ---------------------------------------------------------------------- ,---------------------------------------------------------------------, GOSUBGOSUB [key:]label | | GOSUBGOSUB [key:]label (p1,p2,p3,...,p9) | | `---------------------------------------------------------------------' Calls a macro procedure (subroutine). This allows you to define blocks of macro code that function as subroutines. A RETURN instruction is used by the called procedure to cause execution to return to the line following the GOSUB. Labels within a macro definition are considered private. The same label may be used again in a different macro definition with no ill effect. If you wish to call a procedure in a different definition, prefix its label with the name of the key for that definition, separated by a colon (i.e. GOSUB F10:GET_PORT) Labels defined under a [PUBLIC] definition however, are accessible by all macro definitions without having to give a prefix before the label's name. For more information on [PUBLIC] refer to page 21. This command also allows up to nine parameters to be passed to the subroutine being called. Inside the subroutine the parameters are available as %P1..%P9. The definitions of %P1..%P9 will change appropriately for each nested call to a deeper subroutine, and then return to what they were when the prior level resumes. if one of the parameters that needs to be passed contains a comma or closing parenthesis, surround the parameter in angle brackets to keep either of the characters from terminating the parameter earlier than desired (i.e. "GOSUB TEST (Names,<Joe,Tom,Dick>)"). See also: GOTO, [PUBLIC], %P1..%P9 46 Macro Language - Macro Command Reference ---------------------------------------------------------------------- Example: MAIN MENU ;;MENU TITLE [F1] PRINT A FILE ;;TITLE LINE AND SWITCHES SELECT *.* Pick a File ;;DISPLAY MENU OF FILES GOSUBGOSUB GET_PORT ;;GET PRINTER PORT IN %PORT PRINTFIL %FE,%PORT ;;PRINT THE FILE . . ;;--- START OF PUBLIC MACRO PROCEDURES ------------------------- [PUBLIC] ;;START OF PUBLIC SUBROUTINES :GET_PORT ;;GET PRINTER PORT IN %PORT MENU Printer Port,Lpt1,Lpt2,Lpt3 ;;DISPLAY MENU OF OPTIONS %PORT=%MT ;;%PORT=MENU SELECTION PICKED RETURN ;;RETURN TO CALLER In this example a procedure called GET_PORT is defined under the [PUBLIC] definition. It is called by the F1 key to let the user select which printer port the file should be printed to. ,---------------------------------------------------------------------, GOSUBMFGOSUBMF [d:][path]macrofile [/key][/c] | | GOSUBMFGOSUBMF [d:][path]macrofile (p1,p2,p3,...,p9) [/key][/c] | | `---------------------------------------------------------------------' Loads a new macro file, saving the current macro filename on the gosub stack. If the menu mode is not active, the function key menu overlay will pop-up as if Backspace had been pressed in the file handler. As long as a gosub'd macro file is active, the function key menu overlay will continue to reappear after function keys are executed. Pressing Escape will cancel the function key overlay menu and also return to the base macro file, popping off any gosub'd macro files that may lie in between. If the menu mode is active, pressing Escape on a gosub'd macro file's menu will perform an automatic RETURN to the previous macro file. A macro key executed from a gosub'd macro file can itself force a return to the previous macro file by issuing a macro RETURN command. When a macro file is returned to, execution of the next line following the GOSUBMF will resume. The gosub stack can hold approx. 9+ nested macro filenames (depending on their length). 47 Macro Language - Macro Command Reference ---------------------------------------------------------------------- An optional path may be specified prior to the macro filename. If no path is specified, the macro file is assumed to be located in dCOM's home directory. If an optional key (e.g. F1 or sF10) is specified, the macro key(s) are executed immediately after the new macro file loads. Multiple key's can be given by preceding their occurrence(s) with a "/". Multiple key's are executed in numerical order, not the order specified. This command also allows up to nine parameters to be passed to the macro file being called. Inside the macro file the parameters are available as %P1..%P9. The definitions of %P1..%P9 will change appropriately for each nested call to a deeper subroutine, and then return to what they were when the prior level resumes. if one of the parameters that needs to be passed contains a comma or closing parenthesis, surround the parameter in angle brackets to keep either of the characters from terminating the parameter earlier than desired (i.e. "GOSUBMF UTILS.MAC (Names,<Joe,Tom,Dick>)"). Using GOSUBMF is the key to building layered menuing structures. Refer to Menuing on page 119 for more information. Optional Switches: /C/C Causes the gosub'd macro menu to display cascaded a level deeper than the previous menu, allowing the title of the previous macro file to remain visible behind the new macro menu. Multiple levels of cascading may be used for as much room remains on the screen. If more than three levels are used, a MENUSTART command (in a [MENUAUTO] definition) may be needed to shift the start of the displayed menu's higher on the screen. See also: GOTOMF, RETURN, %P1..%P9 48 Macro Language - Macro Command Reference ---------------------------------------------------------------------- Example: MAIN MENU ;;MENU TITLE [F1] FORMAT DISK MENU ;;TITLE LINE AND SWITCHES GOSUBMFGOSUBMF FORMAT /C ;;CALL FORMAT MACRO FILE [F2] WORD PROC MENU ;;TITLE LINE AND SWITCHES GOSUBMFGOSUBMF WORDPROC /C ;;CALL WORDPROC MACRO FILE [F3] UTILITY MENU ;;TITLE LINE AND SWITCHES GOSUBMFGOSUBMF UTILITYS /C ;;CALL UTILITYS MACRO FILE * * [F10] RET TO MAIN MENU ;;TITLE LINE AND SWITCHES RETURNRETURN ;;RETURN TO PREVIOUS MACRO FILE This example provides options to call FORMAT.MAC, WORDPROC.MAC, and UTILITYS.MAC, and an option to return to the previous macro file. ,---------------------------------------------------------------------, GOTOGOTO [key:]label | | `---------------------------------------------------------------------' Jumps unconditionally to the label specified. Labels within a macro key are considered local. The same label may be defined again in a different macro key with no ill effect. If you wish to jump to a label in a different macro key, prefix the label with the name of that key, separated by a colon. See also: GOSUB, ONBREAKGOTO, ONERRORGOTO ,---------------------------------------------------------------------, GOTOMFGOTOMF [d:][path]macrofile [/key] | | `---------------------------------------------------------------------' Specifies and loads a new active macro file but does not save any return information. An optional path may be specified prior to the macro filename. If no path is specified, the macro file is assumed to be located in dCOM's home directory. If the optional key (e.g. F1 or SF10) is also specified, the specified macro key(s) are executed immediately after the new macro file loads. Multiple key's can be given by preceding their occurrence(s) with a "/". Multiple key's are executed in numerical order, not the order specified. 49 Macro Language - Macro Command Reference ---------------------------------------------------------------------- See also: GOSUBMF ,---------------------------------------------------------------------, IFIF [NOT] operand1 <=> operand2 command | | IFIF [NOT] operand1 <=> operand2 [THENTHEN] | | `---------------------------------------------------------------------' Executes a command or block of commands if the result of the expression is true. If Operand2 contains embedded spaces, it must be enclosed in double quotation marks. Spaces are used to delimit the second operand from the command that follows. If Operand2 is enclosed in quotes, the quotes are removed before the comparison is performed. Do not also follow suite and enclose Operand1 in quotes. Operand1 does not automatically strip out quotation marks and they would be included as part of the comparison. If you are using an IF command with relational operators ("<", "=", or ">"), at least one must be specified, but more than one can be used. If both operands are comprised totally of numeric characters (0..9, "+", "-", "*", or "/"), a 32-bit signed comparison is performed and in-line arithmetic can be used (i.e. IF 3+4>6 THEN). When operands are not numeric, the comparison is not case sensitive. If operand1 is shorter than operand2 but equal to it for as many characters as it contains, it will be considered less than operand2. If date variables are being used as the operands, both operands should be equally quoted in something other than double quotation marks (any character will do) to force a text-based comparison. Otherwise, they will look like numeric expressions using in-line arithmetic (i.e. 06-27-91 = -112, or 06/27/91 = 0) and the numeric results will be the determining factor of the comparison. For more information refer to IF Statements on page 26. See also: ELSE, ELSEIF, ENDIF 50 Macro Language - Macro Command Reference ---------------------------------------------------------------------- Examples: [F1] CHKDSK /w ;;TITLE LINE AND SWITCHES CHKDSK C: ;;CHECK DRIVE C: INTEGRITY IFIF %EL>0 THENTHEN ;;IF ERRORLEVEL GREATER THAN 0 BEEP ;; BEEP ECHO Errors Found on Drive C:! ;; ECHO ERRORS FOUND ELSEELSE ;;ELSE ECHO Drive C: Has No Errors ;; ECHO NO ERRORS ENDIFENDIF ;;END OF IF BLOCK [F1] FORMAT A: ;;TITLE LINE AND SWITCHES BEEP ;;BEEP SPEAKER MENU Are You Sure?,Yup,Heck No ;;ASK FOR PERMISSION IFIF %MT="YUP" FORMAT A: ;;IF ANSWER WAS YES, DO IT ,---------------------------------------------------------------------, IFIF [NOT] EOFEOF [#]filenumber | | IFIF [NOT] EOFEOF [#]filenumber [THENTHEN] | | `---------------------------------------------------------------------' Executes a command or block of commands depending on whether the specified file number is at the end of file. The file number must previously have been opened with an OPEN or CREATE command. The file number can be expressed with or without the pound symbol ("#"), and it can optionally be enclosed in parenthesis, depending on preference. For more information refer to IF Statements on page 26. See also: ELSE, ELSEIF, ENDIF Example: OPEN #1,C:\AUTOEXEC.BAT ;;OPEN THE AUTOEXEC.BAT FILE :LABEL1 ;;JUMP POINT FOR READING IF NOT EOF (#1) THEN ;;IF NOT END OF FILE READLN #1,%TEXT ;; %TEXT=NEXT LINE ECHO %TEXT ;; DISPLAY IT GOTO LABEL1 ;; LOOP BACK FOR NEXT LINE ENDIF ;;END OF IF BLOCK Note: This particular example could have been written more efficiently using a DO WHILE NOT EOF loop instead of IF NOT EOF. 51 Macro Language - Macro Command Reference ---------------------------------------------------------------------- ,---------------------------------------------------------------------, IFIF [NOT] ERRORLEVEL nERRORLEVEL n command | | IFIF [NOT] ERRORLEVEL n ERRORLEVEL n [THENTHEN] | | `---------------------------------------------------------------------' This variation of the IF command is provided for batch file compatibility. The IF condition is true if the last program executed returned an error level equal to or greater than value n. The same test can be performed in a more readable manner using the %EL macro variable (i.e. IF %EL>0 GOTO ERROR). See also: ELSE, ELSEIF, ENDIF, %EL Example: [F1] COMPILE FILE /w ;;TITLE LINE AND SWITCHES MASM %FN,,%FN; ;;COMPILE SELECTED FILE IF ERRORLEVELIF ERRORLEVEL 1 GOTO ERROR ;;IF ERROR GOTO ERROR LINK %FN; ;;LINK THE PROGRAM IF ERRORLEVELIF ERRORLEVEL 1 GOTO ERROR ;;IF ERROR GOTO ERROR DEL %FN.OBJ ;;DELETE THE .OBJ FILE EXIT ;;EXIT THE MACRO KEY :ERROR ;;LABEL FOR GOTO ERROR BEEP ;;BEEP THE SPEAKER ,---------------------------------------------------------------------, IFIF [NOT] EXISTEXIST [path]filename command | | IFIF [NOT] EXISTEXIST [path]filename [THENTHEN] | | `---------------------------------------------------------------------' Executes a command or block of commands based on whether the specified file exists (or does NOT exist). The filename specified may include wildcards or a subdirectory's name. An exist test will test true if the file has a hidden or system flag set. You can also use this command to test on whether a drive exists by testing against "d:\NUL". For more information refer to IF Statements on page 26. See also: ELSE, ELSEIF, ENDIF 52 Macro Language - Macro Command Reference ---------------------------------------------------------------------- Example: [F1] MOVE .BAK FILES ;;TITLE LINE AND SWITCHES IF EXISTIF EXIST *.BAK THENTHEN ;;IF THERE ARE ANY .BAK FILES COPY *.BAK D:\BACKUP ;; THEN COPY THEM TO D:\BACKUP DEL *.BAK ;; AND THEN DELETE THEM ENDIFENDIF ;;END OF IF BLOCK ,---------------------------------------------------------------------, INCLUDEINCLUDE [d:][path]filename | | `---------------------------------------------------------------------' Includes another text file as part of the current macro file. Include files are useful for holding commonly used subroutines under a [PUBLIC] definition, that more than one macro file might want to access. Or, for setting global static variables under a [EQUATES] definition. An optional path may be specified prior to the include filename. If no path is specified, the include file is assumed to be located in dCOM's home directory. No default extension is assumed with the include filename. INCLUDE files can be nested up to 16 levels deep. The total number of INCLUDE commands that may be invoked by a macro file and its included files is 255. Unlike almost all other macro commands, the INCLUDE command is handled by the internal compiler - not by the macro engine during runtime. Compiled macro files (the hidden .CMF files), contain the effects of included files when they are written by the compiler. If a file I/O error occurs while the macro compiler is opening or reading an include file, a real-time error is displayed indicating the problem. After which, the include file is abandoned and the macro compiler continues compiling the macro code that attempted to call the include file. The error message will only occur just once until the next time the macro system thinks it needs to recompile that macro file. An INCLUDE command can occur as the first significant line of a macro file, which is normally reserved for the macro's menu title. In this case, the macro compiler will internally flag the title as having been set, even though it actually hasn't. The macro title can still be set though by using a subsequent MENUTITLE command. INCLUDE and MENUTITLE are the only commands recognizable before the first macro definition starts in a macro file. For more information refer to Include Files on page 123. See also: MENUTITLE 53 Macro Language - Macro Command Reference ---------------------------------------------------------------------- Example: INCLUDE MYPROCS.INC ;;INCLUDE MYPROCS.INC FILE ,---------------------------------------------------------------------, KEYBOARDKEYBOARD text | | `---------------------------------------------------------------------' Stuffs the keyboard type-ahead queue with text. This command is provided as a simple 'down-n-dirty' method to stuff ASCII characters in the keyboard queue. It doesn't bother to also include scan codes which, might be needed by some applications. The maximum length of the text is 15 characters (which is the size of the BIOS keyboard queue). Also, a Return is not automatically installed after the text. If you need one, append a %(13) to the text used. Example: [F1] HARVARD PROJ MGR ;;TITLE LINE AND SWITCHES KEYBOARD C:\BAT\HTPM%(13) ;;STUFF KEYBRD W/WHAT TO DO NEXT EXITDCOM /n ;;EXIT DCOM W/NO EXIT PROMPTS This example stuffs "C:\BAT\HTPM<RET>" in the keyboard queue and then exits dCOM. It assumes there's a batch file in directory C:\BAT called HTPM.BAT, which runs Harvard Project Manager and would then rerun dCOM again when its finished. This works ok if COMMAND.COM ran dCOM. If dCOM was loaded as the primary shell in CONFIG.SYS, there's nothing to exit to, and the EXITDCOM command will fail. ,---------------------------------------------------------------------, KEYWAITKEYWAIT | | `---------------------------------------------------------------------' Pauses macro execution and waits for any keyboard character to be pressed. Unlike the PAUSE command, this command does not disturb the video display. KEYWAIT is mouse sensitive. Pressing the left mouse button will act as if the Return key was pressed. The right button as if Escape was pressed. You can check which key was pressed afterwards by testing the %EL system variable. If %EL is greater than 255, a non-alpha key (function keys, cursor keys, etc...) was pressed. If %EL is 255 or less, it will contain the key's ASCII value (i.e. "A"=65, "B"=66, etc...). If the Return key was pressed, %EL will equal 13. 54 Macro Language - Macro Command Reference ---------------------------------------------------------------------- If the Escape key is pressed, the macro key aborts execution unless trapped with ONBREAKGOTO. See also: PAUSE ,---------------------------------------------------------------------, LOOPLOOP label | | `---------------------------------------------------------------------' Loops back to the label specified for each occurrence of a tagged file. Within a LOOP block, the %TN and %TE variables are used to access the current iteration's filename, or filename and extension (respectively). If no files are tagged, the %TN or %TE variables will return the currently selected filename (or filename and extension), and the LOOP command will execute for only one iteration. If your macro absolutely wants tagged files, test on the value of %TC before entering the loop block. Example: [F1] ARCHIVE TAGGED /W ;;TITLE LINE AND SWITCHES IF %TC%TC < 1 THEN ;;IF THERE ARE NO TAGGED FILES BEEP ;; THEN BEEP THE SPEAKER MENU Tagged Files Required ;; USE MENU COMMAND TO .Press Return to Continue ;; DISPLAY ERROR EXIT ;; TERMINATE THE MACRO KEY ENDIF ;;END OF IF BLOCK GET %FILE Enter Zip File: ;;GET A FILENAME IN %FILE :LABEL1:LABEL1 ;;START OF LOOP BLOCK ECHO Zipping %TE%TE to %FILE ;; DISPLAY CURRENT LOOP FILE PKZIP %FILE %TE%TE >NUL ;; ADD IT TO .ZIP FILE LOOP LABEL1LOOP LABEL1 ;;LOOP THROUGH TAGGED FILES ,---------------------------------------------------------------------, MACROMENUMACROMENU ON|OFF | | `---------------------------------------------------------------------' If the menu mode is active, a MACROMENU OFF command will deactivate (suspend) the menu mode, causing control to drop to the file handler when macro execution terminates. If the menu mode is active but has been suspended, a MACROMENU ON will reactivate the menu mode when macro execution terminates. If the menu mode is not active (dCOM's /M command line switch wasn't specified at start up), a MACROMENU ON command will cause the function key overlay to appear when macro execution terminates (as 55 Macro Language - Macro Command Reference ---------------------------------------------------------------------- if Backspace were pressed in the file handler). When the function key overlay menu is activated in this manner, it becomes "sticky" about wanting to stay active. It will continue to reappear after macro keys are executed until it is explicitly escaped. Normally however, when the function key overlay menu is activated with Backspace it will not reappear after one of the macro keys is executed unless the macro key gosubs another macro file. In this case, the function key overlay will continue to reappear after macro keys are executed as long as a macro file is gosub'd. Using this command in either fashion is not normally required. See also: %MM ,---------------------------------------------------------------------, MDMD [d:][path]dirname | | MKDIRMKDIR [d:][path]dirname | | `---------------------------------------------------------------------' Makes a new subdirectory. This macro command is functionally equivalent with its MS-DOS counterpart except that it can make more than one new directory in a given path simultaneously. For instance, if C:\DOCS did not already exist as a subdirectory, when a MD C:\DOCS\REPORTS command was encountered, dCOM would build both directories without an error, but MS-DOS would 'choke'. See also: RD ,---------------------------------------------------------------------, MENUMENU [title],sel1,sel2[,sel3][,sel4...] | | `---------------------------------------------------------------------' Displays a user designed pop-up menu. This command lets you build your own point-n-shoot, mouse-sensitive menus. The results of the option selected can then be accessed in following macro lines using the %MT and %MS system variables. %MT returns the text of the option selected. %MS returns a numerical value indicating the line number selected (1=1st, 2=2nd...). The first parameter expected is the menu's title. The title is then followed by the options you wish displayed, separated with commas. If no title is used, the first selection must be preceded with a comma. MENU commands also recognize the use of continuation lines. This may be necessary to avoid overrunning the macro engine's internal line length of 512 characters, or just to express the macro code in a manner more representative of the actual menu. Any macro line following a MENU command whose first significant character begins with a period is considered a continuation line. If continuation 56 Macro Language - Macro Command Reference ---------------------------------------------------------------------- lines are used, it is not necessary to terminate the preceding line with a trailing comma. If the menu is cancelled with the Escape key or mouse right button, macro execution aborts unless trapped with ONBREAKGOTO. Refer to the ONBREAKGOTO command for an example of how to trap the Escape key and build submenus. This command also recognizes the menuing-type switches described on page 30. See also: MENUCOLOR, SELECT, %MS, %MT Examples: [F1] FORMAT ;;TITLE LINE AND SWITCHES MENU FORMAT,A:,B: ;;DISPLAY FORMAT DRIVE OPTIONS %DRIVE=%MT ;;SAVE IT IN %DRIVE MENU FORMAT %DRIVE ;;DISPLAY THE .360K ;; FORMAT /F: OPTIONS .720K ;; USING A MENU COMMAND .1.2M ;; WITH CONTINUATION LINES .1.44M ;;DISPLAY FORMAT /F: OPTIONS FORMAT %DRIVE /F:%MT ;;RUN FORMAT WITH SELECTIONS [F1] FORMAT A: ;;TITLE LINE AND SWITCHES BEEP ;;BEEP SPEAKER MENU Are You Sure?,Yes,No ;;ASK FOR PERMISSION IF %MS=1 FORMAT A: ;;IF ANSWER WAS YES, DO IT The MENU command also has another feature designed primarily for use on a network, which allows individual entries in the menu to be conditional upon whether an exist test for a file or directory is true for the current user. If the exist test fails, the user won't see the particular option. Conditional menu options are expressed by separating the menu text from the exist test with a semicolon (or tab). 57 Macro Language - Macro Command Reference ---------------------------------------------------------------------- For example: [F1] APPLICATIONS ;;TITLE LINE AND SWITCHES MENU APPLICATIONS ;;MENU COMMAND AND ITS TITLE .WORDSTAR;F:\WS6LAN\WS.EXE ;; CONDITIONAL 1ST OPTION .HARVARD;F:\HG\HG.EXE ;; CONDITIONAL 2ND OPTION GOTO %MT ;;GOTO OPTION PICKED :WORDSTAR ;;WORDSTAR OPTION CDD F:\WS6LAN ;; CHANGE DRIVE AND DIRECTORIES WS ;; RUN WORDSTAR CDDO ;; RETURN TO ORIG DRIVE & DIR EXIT ;; AND TERMINATE MACRO :HARVARD ;;HARVARD OPTION CDD F:\HG ;; CHANGE DRIVE AND DIRECTORIES HG ;; RUN HARVARD GRAPHICS CDDO ;; RETURN TO ORIG DRIVE & DIR EXIT ;; AND TERMINATE MACRO This example only displays the Wordstar and Harvard options if the user has sufficient privileges to see their executable files. If you are using NetWare 3.0 or greater, the exist path could be shortened down to just the directory name itself because users can't see a subdirectory name at all if they don't have any privileges in it. Note that the %MT system variable is used to determine which option was picked (GOTO %MT). When you are using conditional menu options, the number of the selection picked can vary between users, making the %MS variable unreliable. Also, the macro code depicted that actually runs the applications is probably nowhere near as comprehensive as it would normally be for network use. ,---------------------------------------------------------------------, MENUCOLORMENUCOLOR fc,bc,blc,hc[,bt] | | `---------------------------------------------------------------------' Overrides the default colors used by any subsequent menuing-type command. This command also overrides the menu mode's function key menu colors if used in a [MENUAUTO] definition. If a MENUCOLOR command is executed when the EGA palette is still remapped to non-CGA colors, an automatic clear screen will be issued to restore the EGA palette back to normal. 58 Macro Language - Macro Command Reference ---------------------------------------------------------------------- fc fc The menu selection text foreground color (0..15) bc bc The menu background color (0..7) blc blc The foreground color of the border lines (0..15) hc hc The foreground color of the header text (0..15) bt bt An optional border line-type override (1..4). 1 = single- width lines, 2 = double-width lines, 3 = solid lines, 4 = no border lines. If this value isn't specified, menus will use whatever line type the file handler is configured for. See also: MENU, SELECT, APPMENU, QFORMAT Example: MENUCOLOR 0,3,1,14,2 ;;SET MENU COLORS/BORDER TYPE MENU What Do You Think?,Yes,No ;;DISPLAY A MENU USING THEM ,---------------------------------------------------------------------, MENUSTARTMENUSTART line,column | | `---------------------------------------------------------------------' Overrides the default display position of the function key menu when the menu mode is active. Normally the function key menu is displayed centered in the middle of the screen. You may want to adjust this though if you use a [MENUAUTO] definition to display some other information, or if you make extensive use of cascaded submenus (the GOSUBMF command with a /C switch). The line and column specified refer to the top left corner of the menu. This command is only recognized in a [MENUAUTO] definition. If you use this command in the [MENUAUTO] definition of a macro file that calls another macro file using GOSUBMF with the /C switch, the called macro file should also contain a [MENUAUTO] definition with the same MENUSTART parameters. See also: MENUCOLOR Example: MENUSTART 8,14 ;;OVERRIDE MENU DISPLAY POSITION ,---------------------------------------------------------------------, MENUTITLEMENUTITLE title | | `---------------------------------------------------------------------' Sets the title of the macro file's menu. 59 Macro Language - Macro Command Reference ---------------------------------------------------------------------- Normally the first significant line of a macro file is used to set the menu title. This command is provided as an optional way to set the menu title if the first line is needed for something else, like an INCLUDE command. INCLUDE and MENUTITLE are the only commands recognizable before the first macro definition starts in a macro file. Unlike almost all other macro commands, this command is handled by the internal compiler - not by the macro engine during runtime. This means you can't do something like nest it in an IF block and expect different menu titles depending on certain conditions. Example: MENUTITLE Main Menu ;;SET THE MENU TITLE ,---------------------------------------------------------------------, MULMUL destination,source | | `---------------------------------------------------------------------' Performs a 32-bit signed integer multiply operation using the two operands. The destination operand must be a user variable. The source operand can be a combination of literal text and/or macro variables. The source operand can also include in-line arithmetic, which is evaluated from left to right without regard for standard algebraic order (i.e. multiplication before addition). The result of the operation is returned in the destination user variable. See also: ADD, SUB, DIV Examples: %VAR1=12 ;;%VAR1 = 12 %VAR2=23 ;;%VAR2 = 23 MUL %VAR1,2 ;;%VAR1 = 24 (12*2) MUL %VAR1,%VAR2 ;;%VAR1 = 552 (24*23) MUL %VAR1,%VAR2+3*2 ;;%VAR1 = 28704 (552*((23+3)*2)) ,---------------------------------------------------------------------, ONBREAKGOTOONBREAKGOTO [key:]label | | `---------------------------------------------------------------------' Traps the Escape key when menus or prompts are active and also traps Ctrl-C aborts at any time. If no trap is set with this command, either pressing Escape during any macro command that pauses for a keyboard response, or pressing 60 Macro Language - Macro Command Reference ---------------------------------------------------------------------- Ctrl-C at any time that the macro engine is executing, will cause macro execution to abort immediately. The label specified is where execution jumps to if an abort occurs. If no label is specified, break trapping is cancelled. The rules governing the use of labels are the same as those for the GOTO or GOSUB macro commands. Break trapping is automatically reset when a new macro file loads. One use for this command is to build layered submenus that return to the previous menu when Escape is pressed. Another would be to trap the Escape key when a gosub'd macro file is running as a program under a [FILEAUTO] definition, and it should always RETURN to the previous macro file. Example: [F1] SUB MENUS ;;TITLE LINE AND SWITCHES :MAIN_MENU ;;MAIN MENU JUMP POINT ONBREAKGOTO ;;RESET TRAP SO MAC CAN ABORT MENU Main Menu,Go,Jump ;;DISPLAY MAIN MENU GOTO %MT ;;GOTO OPTION PICKED :GO ;;GO MENU JUMP POINT ONBREAKGOTO MAIN_MENU ;; SET ESC TRAP TO MAIN MENU MENU Go Where?,Home,Sleep ;; DISPLAY GO MENU ONBREAKGOTO GO ;; SET ESC TRAP TO GO MENU MENU Can't Go to %MT ;; ABUSE USER WITH .Press Return to Continue ;; MENU RESPONSE GOTO GO ;; GO BACK TO GO MENU :JUMP ;;JUMP MENU JUMP POINT ONBREAKGOTO MAIN_MENU ;; SET ESC TRAP TO MAIN MENU MENU How High?,12",24",48" ;; DISPLAY JUMP MENU ONBREAKGOTO JUMP ;; SET ESC TRAP TO JUMP MENU MENU Can't Jump %MT ;; ABUSE USER WITH .Press Return to Continue ;; MENU RESPONSE GOTO JUMP ;; GO BACK TO JUMP MENU ,---------------------------------------------------------------------, ONERRORGOTOONERRORGOTO [key:]label | | `---------------------------------------------------------------------' Traps runtime errors. If no trap is set with this command, macro runtime errors will produce a dialog box that describes the error and shows the line that caused it. Macro execution then terminates immediately. The label specified is where execution jumps to if an error occurs. If no label is specified, error trapping is cancelled. The rules governing the use of labels are the same as those for the GOTO or GOSUB macro commands. 61 Macro Language - Macro Command Reference ---------------------------------------------------------------------- Error trapping is automatically reset when a new macro file loads. When control jumps to an error handler, it should immediately reset error trapping to avoid the possibility of an endless loop. While an error handler is active, %ET will contain the exact text of the error, %EL will equal the error number (refer to the appendices for error number descriptions), and %LE will return the line number of the error in the macro file. If the error handler only wants to check for something, or close something, and then terminate using the macro engine's normal error handler, it could then just issue an undocumented command to display the error. See also: %EL, %ET, %LE Example: ONERRORGOTO ERROR ;;SET ERROR TRAP OPEN #1,C:\MYDATA.TXT ;;ATTEMPT TO OPEN A FILE DO WHILE NOT EOF (1) ;;DO WHILE NOT END OF FILE READLN #1,%TEXT ;; %TEXT=NEXT LINE ECHO %TEXT ;; DISPLAY IT ENDDO ;;END OF DO WHILE BLOCK CLOSE ;;CLOSE ALL OPEN FILES EXIT ;;EXIT THE MACRO :ERROR ;;ERROR HANDLER ONERRORGOTO ;;RESET ERROR TRAPPING CLOSE ;;CLOSE THE FILE BEEP ;;BEEP THE SPEAKER MENU Error: %ET ;;USE MENU COMMAND TO .Press Ret to Continue ;; DISPLAY ERROR TEXT EXIT ;;EXIT THE MACRO ,---------------------------------------------------------------------, OPENOPEN [#]filenumber,[d:][path]filename [/a][/w] | | `---------------------------------------------------------------------' Opens a file for reading or writing and associates it with a file number. The file I/O system loosely follows that of formatted sequential I/O commands in BASIC. It is designed primarily for working with ASCII text files. Before a file can be read or written it must first be opened (or created) and associated with a file number. There are 10 file numbers available (0..9), so you can have as many as 10 files open simultaneously (provided your CONFIG.SYS file has a FILES statement which allows it). Files stay open until macro execution terminates 62 Macro Language - Macro Command Reference ---------------------------------------------------------------------- (at which time they will be closed automatically if any are still left open). If no switches are specified, this command opens a file for read access only, and will fail with an error if the file isn't found. Optional Switches: /A/A Opens the file for appending. When this switch is used, the file is opened for write access and the file position pointer moved to the end of file. If the file isn't found, it is created. /W/W Opens the file for writing. When this switch is used, the file is opened for write access and the file position pointer is at the beginning of file. If the file isn't found, it is created. Using this switch can be dangerous if the lines written are not fixed length, because the previous contents of the file past what is written remain intact. See also: CREATE, READ, READLN, WRITE, CLOSE, %FP Example: OPEN #1,C:\CONFIG.SYS ;;OPEN C:\CONFIG.SYS DO WHILE NOT EOF (1) ;;DO WHILE NOT END OF FILE READLN #1,%TEXT ;; READ NEXT LINE ECHO %TEXT ;; DISPLAY IT ENDDO ;;END OF DO BLOCK CLOSE #1 ;;CLOSE THE FILE ,---------------------------------------------------------------------, PATHPATH [=]path | | `---------------------------------------------------------------------' Sets the MS-DOS PATH environment variable. This command behaves the same as its MS-DOS equivalent. It is mentioned here primarily to indicate that it is an internal macro command handled by the macro engine. See also: PATHADD, PATHDEL, PROMPT, SET ,---------------------------------------------------------------------, PATHADDPATHADD path | | `---------------------------------------------------------------------' Adds an entry to the PATH environment variable. This command provides an on-the-fly method of quickly adding an entry in the path to a program's directory before a macro definition runs it. 63 Macro Language - Macro Command Reference ---------------------------------------------------------------------- If the same entry already exists in the path, it will not be added twice. Multiple path entries can be added using one PATHADD instruction (for example: "PATHADD C:\WORD;C:\DOCS"). When you are adding only a single entry, whether you trail it with a semi-colon is subjective. The PATHADD command will ensure that the entry is installed correctly in the path. If you are adding multiple entries with one PATHADD command, they must be properly separated with a semi-colon, but the trailing semi-colon is still optional. The path text is inserted at the start of the path, which produces a quick response when the program is run by not having to search any other path entries before finding the program's executable file. dCOM's PATH environment is not limited to 128 characters like MS-DOS is (actually its a COMMAND.COM limitation). The only limit is the actual size of the environment. If COMMAND.COM gets mixed up in the middle of running something though, its PATH variable will probably be a truncated version of dCOM's after the 128th character. Note: dCOM has a unique feature where if a path entry begins with an "@" symbol, all subdirectories in that path will be searched instead of the files that are in that path. Refer to the file handler's documentation for more information. See also: PATHDEL, SET Example: [F1] MS-WORD ;;TITLE LINE AND SWITCHES PATHADDPATHADD C:\WORD ;;ADD C:\WORD TO THE PATH WORD ;;RUN MS-WORD PATHDEL C:\WORD ;;REMOVE C:\WORD FROM THE PATH CDDO ;;RETURN TO ORIG DRIVE & DIR ,---------------------------------------------------------------------, PATHDELPATHDEL path | | `---------------------------------------------------------------------' Removes an entry from the PATH environment variable. This command is normally used to remove a path entry that was added with PATHADD, after it is no longer needed. See also: PATHADD, SET 64 Macro Language - Macro Command Reference ---------------------------------------------------------------------- ,---------------------------------------------------------------------, PAUSEPAUSE [text] | | `---------------------------------------------------------------------' Displays the message "Press Return to Proceed or Escape to Cancel" and waits for a proper response. If text is also supplied, it is displayed on the line prior to the pause message. If the Escape key is pressed at the prompt, the macro key aborts execution unless trapped with ONBREAKGOTO. See also: KEYWAIT ,---------------------------------------------------------------------, PRINTFILPRINTFIL [d:][path]filename [/lpt#][/v] | | `---------------------------------------------------------------------' Prints a file. If dCOM's print spooler is enabled, when this command prints a file it passes large "chunks" of the file directly to the spooler, in a very expeditious manner. The filename may include wildcards. This command prints files using the same logic as the file handler. If the file contains one or more escape characters it is considered a binary file and is printed as is. If the file does not contain an escape character, a form-feed will be appended to the output if the last printed character was not a form-feed. And also, if an ASCII End-of-File marker (Ctrl-Z) is encountered, printing will stop at the character before it. Optional Switches: /LPT#/LPT# Specifies which printer port to print the file(s) to (i.e. /LPT1, etc...). If this switch isn't specified, the output will go to the file handler's default printer port. /V/V Causes a verbose display of each file printed that includes a counter which indicates printing progress. See also: PRINTSTR ,---------------------------------------------------------------------, PRINTSTRPRINTSTR text | | `---------------------------------------------------------------------' Sends a text string to the default printer device. 65 Macro Language - Macro Command Reference ---------------------------------------------------------------------- A carriage return/line-feed sequence is NOT automatically appended to the text printed. If one is needed, append a "%(13)%(10)" onto the end of the text. This command properly handles any control codes you might need to send (e.g. Esc = "%(27)", and ASCII null = "%(0)"). You can also use variables embedded inside the system %(nnn) character variable if you want to send a code that was based on something like say what a user selected for the value of a left margin. See also: PRINTFIL Example: [F1] SET COMPRESSED ;;TITLE LINE AND SWITCHES PRINTSTRPRINTSTR %(15) ;;SEND EPSON COMPRESSED CODE ,---------------------------------------------------------------------, PROMPTPROMPT [=]prompt | | `---------------------------------------------------------------------' Sets the MS-DOS PROMPT environment variable. This command behaves the same as its MS-DOS equivalent. It is mentioned here primarily to indicate that it is an internal macro command handled by the macro engine. See also: PATH, SET ,---------------------------------------------------------------------, QFORMATQFORMAT [d:] | | `---------------------------------------------------------------------' Quick Format's a floppy disk, completely erasing its contents. Quick formatting cannot initialize a brand new disk. It works quickly by only resetting directory and FAT information on a disk's boot track. If a drive isn't specified, QFORMAT will prompt for it. A syntax error is produced if a drive other than A: or B: is specified. The status of a QFORMAT operation can be tested afterwards using the %EL (errorlevel) system variable (0=successful, 1=error). This command does not prompt before proceeding if the drive is supplied as a parameter. If you want to provide a confirmation prompt, use the MENU command to do so first. This command also recognizes the menuing-type switches described on page 30. 66 Macro Language - Macro Command Reference ---------------------------------------------------------------------- See also: MENUCOLOR ,---------------------------------------------------------------------, RDRD [d:][path]dirname | | RMDIRRMDIR [d:][path]dirname | | `---------------------------------------------------------------------' Removes (deletes) a subdirectory. The directory being removed must be empty of files and subdirectories. This macro command is functionally equivalent with its MS-DOS counterpart. See also: MD ,---------------------------------------------------------------------, READREAD [#]filenumber[,var][,var][,var][,var...] | | `---------------------------------------------------------------------' Reads the next line from an open file number into a list of user variables. The file number specified must first have been opened with an OPEN command. This command expects fields within the line being read to be comma delimited. If more user variables are specified than fields found, the extra variables will be assigned null values. The file position pointer is advanced to the next line after each READ command, irregardless of whether there were enough user variables to receive the fields in the line read. Macros should do their own end of file checking before issuing a READ command to avoid "Read Past EOF" runtime errors. See also: OPEN, READLN, WRITE, CLOSE, %FP Example: OPEN #1,C:\TESTDAT.TXT ;;OPEN C:\TESTDAT.TXT READ #1,%VAR1,%VAR2,%VAR3 ;;READ IN FIELDS CLOSE #1 ;;CLOSE THE FILE ,---------------------------------------------------------------------, READBREADB [#]filenumber,length,var | | `---------------------------------------------------------------------' Reads from an open file number into a user variable. 67 Macro Language - Macro Command Reference ---------------------------------------------------------------------- The file number specified must first have been opened with an OPEN command. The "length" parameter is the number of bytes to read into the user variable. The file position pointer is advanced to the next byte following that which was read. This command is normally used to read files in a binary fashion as opposed to reading text files with the READ command. Macros should do their own end of file checking before issuing a READB command to avoid "Read Past EOF" runtime errors. This can be done by comparing the %FP system variable against the result of a previously issued %SF() variable. See also: OPEN, READ, WRITEB, CLOSE, %FP ,---------------------------------------------------------------------, READLNREADLN [#]filenumber[,var] | | `---------------------------------------------------------------------' Reads the next line from an open file number into a user variable. The file number specified must first have been opened with an OPEN command. Unlike the READ command which expects fields within the line being read to be comma delimited, this command reads the entire line into one user variable up to the Carriage Return (including commas). The file position pointer is advanced to the next line after each READLN command. Macros should do their own end of file checking before issuing a READLN command to avoid "Read Past EOF" runtime errors. See also: OPEN, READ, WRITE, CLOSE, %FP, %TL, %TR Example: OPEN #1,C:\CONFIG.SYS ;;OPEN C:\CONFIG.SYS DO WHILE NOT EOF (1) ;;DO WHILE NOT END OF FILE READLN #1,%TEXT ;; READ NEXT LINE ECHO %TEXT ;; DISPLAY IT ENDDO ;;END OF DO BLOCK CLOSE #1 ;;CLOSE THE FILE ,---------------------------------------------------------------------, REBOOTREBOOT [/c] | | `---------------------------------------------------------------------' Causes the computer to reset and do a warm boot. 68 Macro Language - Macro Command Reference ---------------------------------------------------------------------- Optional Switches: /C/C Forces a cold boot instead of a warm boot. ,---------------------------------------------------------------------, RECOMPILERECOMPILE [d:][path]macrofile [/v] | | `---------------------------------------------------------------------' Manually recompiles a macro file. This is an advanced command which is normally not necessary. The macro engine automatically recompiles macro files when needed. It won't however, automatically detect when an include file has been modified. This command might also be needed on a network so that the administrator can recompile all network macro files, ensuring that all .CMF files are current because normal network users might not have sufficient rights to rewrite them under their login privileges, or when one or more of the macro files make use of a common include file that has been changed. The filename may include wildcards, but the extension is assumed to be ".MAC". An optional path may be specified prior to the macro filename. If no path is specified, the macro file(s) are assumed to be located in dCOM's home directory. Optional Switches: /V/V Causes a verbose display of each macro file compiled. See also: INCLUDE ,---------------------------------------------------------------------, REMREM [text] | | `---------------------------------------------------------------------' Used to include a remark or comment text. Remark lines are ignored when compiled and consume no memory. ,---------------------------------------------------------------------, RETURNRETURN | | `---------------------------------------------------------------------' Returns from either a procedure GOSUB or a macro file GOSUBMF, depending on which was last used. If GOSUBMF was last used, the previous macro file is reloaded and execution resumes with the line following the GOSUBMF statement. If RETURN is encountered and nothing has been gosub'd to, no action is taken and execution continues with the following macro line. 69 Macro Language - Macro Command Reference ---------------------------------------------------------------------- See also: GOSUB, GOSUBMF ,---------------------------------------------------------------------, RSTWINRSTWIN [/n] | | `---------------------------------------------------------------------' Restores the video screen back to the way it was before a WINDOW command was used. Video attributes also included by this are cursor position, active colors/attributes, window boundaries, etc.... Optional Switches: /N/N If the last action saved on the window stack was a WINDOW command, this option properly 'pops' the saved window off the windowing stack and restores the saved video attributes (cursor position, active colors, etc...), but it leaves the window on the screen instead of replacing the window with its previous contents. See also: WINDOW Example: WINDOW 1,1,3,80,1,7,1,1 ;;DISPLAY A BOX ON THE SCREEN CPOSN ,40 ;;POSITION TO CENTER OF WINDOW ECHOC This Screen's Title; ;;ECHO TEXT CENTERED ON CURSOR RSTWIN /N ;;FREE WIN MEM, BUT KEEP BOX ,---------------------------------------------------------------------, RUNMACRORUNMACRO key | | `---------------------------------------------------------------------' Causes execution to jump to the macro key specified. Multiple key's can be given by preceding their occurrence(s) with a "/". Example: [MENUAUTO] ;;RUNS BEFORE MENU DISPLAYS RUNMACRO RUNMACRO F10 ;;EXECUTE THE F10 KEY ,---------------------------------------------------------------------, SELECTSELECT [d:][path]mask [title] [/d][/h][/n][/p][/v] | | `---------------------------------------------------------------------' Displays a menu of files found in mask. A selected filename can then be accessed in following macro lines using the %SN and %SE system variables. The count of files found with the mask can be accessed with the %SC system variable. 70 Macro Language - Macro Command Reference ---------------------------------------------------------------------- If no files qualify with the mask, no menu is displayed and execution continues with the following macro line. The %SN and %SE variables will then return a null string. If needed, this condition can be tested for using the %SC variable in an IF command, after the SELECT command. If the menu is cancelled with the Escape key or mouse right button, macro execution aborts unless trapped with ONBREAKGOTO. Any text following the mask will be displayed as header text above the menu of files found. This command also recognizes the menuing-type switches described on page 30. 71 Macro Language - Macro Command Reference ---------------------------------------------------------------------- Optional Switches: /D/D Specifies that subdirectory entries are to be found and displayed instead of files. /H/H Specifies that hidden files (or subdirectories) are to be shown as well. /N/N Specifies that a "[NewFile]" option should also be displayed. If "[NewFile]" is selected, the %SN and %SE variables will return a null (empty) string. If you then run a program only using one of these variables as its parameters, a lot of programs will then assume a new file since it just received nothing on its command line. If you wish to test whether "[NewFile]" has been selected before running the program, you could use the IF command as follows: "IF %SE="" THEN...". /P/P Allows the menu to dynamically select files in different subdirectories (or drives) than that which the menu initially started with. When this switch is used, the SELECT menu shows both subdirectories and files. When a subdirectory is selected, the menu reappears showing the files in that directory. If the "[..]" entry is selected from the root directory, the user is then given the option to change drives. When this switch is used, %SP should be used in combination with %SN or %SE to determine the full path of the entry selected. Using the /P switch does not change the current directory. Whether hidden directories show when this switch is used is governed by the current user's access control privileges. Whether hidden files are shown is controlled by this command's /H switch. /V/V Causes the SELECT command to display a list of valid drive letters to select from instead of found files. When this switch is used, SELECT does not expect a file mask. The entire text passed (except switches) is considered the menu title. See also: MENU, MENUCOLOR, %SN, %SE, %SP 72 Macro Language - Macro Command Reference ---------------------------------------------------------------------- Example: [F1] RUN MS-WORD ;;TITLE LINE AND SWITCHES C: ;;SET DRIVE C AS DEFAULT CD \WORD ;;CHANGE DIR'S TO \WORD SELECTSELECT *.doc Pick a File /N ;;PICK A FILE TO EDIT WORD %SE%SE ;;RUN MS-WORD WITH THE FILE CD \ ;;CHANGE DIR'S BACK TO ROOT CDDO ;;RETURN TO ORIG DRIVE & DIR ,---------------------------------------------------------------------, SETSET envvar=text | | `---------------------------------------------------------------------' Sets an environment variable. An environment variable can be set to itself plus additional text by using: "SET PATH=%[PATH];c:\test". This command behaves identically with its MS-DOS counterpart except that it doesn't "puke" when environment space is full. ,---------------------------------------------------------------------, SHIPSHIP | | `---------------------------------------------------------------------' Ships (parks) the heads on all internal hard disks present. Macro execution will continue after the SHIP command finishes, so you need to provide your own pause message to ensure no disk activity occurs afterwards. Example: [F10] SHIP HARD DISK ;;TITLE LINE AND SWITCHES SHIPSHIP ;;SHIP THE HARD DISK(S) MENU Hard Disks Shipped ;;DISPLAY MENU .Shut Down ;; FOR WHAT TO .Abort ;; DO NEXT IF %MS=1 THEN ;;IF RESPONSE IS SHUT DOWN CLS ;; CLEAR THE SCREEN BEEP ;; BEEP SPEAKER ECHO Turn Power Off Now; ;; TELL USER WHAT TO DO :LOCKCITY ;; LABEL TO LOCK COMPUTER WITH GOTO LOCKCITY ;; ENDLESS LOOP ENDIF ;;END OF IF BLOCK 73 Macro Language - Macro Command Reference ---------------------------------------------------------------------- ,---------------------------------------------------------------------, SUBSUB destination,source | | `---------------------------------------------------------------------' Performs a 32-bit signed integer subtract operation using the two operands. The destination operand must be a user variable. The source operand can be a combination of literal text and/or macro variables. The source operand can also include in-line arithmetic, which is evaluated from left to right without regard for standard algebraic order (i.e. multiplication before addition). The result of the operation is returned in the destination user variable. See also: ADD, MUL, DIV Examples: %VAR1=23 ;;%VAR1 = 23 %VAR2=12 ;;%VAR2 = 12 SUB %VAR1,1 ;;%VAR1 = 22 (23-1) SUB %VAR1,%VAR2 ;;%VAR1 = 10 (22-12) SUB %VAR1,%VAR2+3*2 ;;%VAR1 = -20 (10-((12+3)*2)) ,---------------------------------------------------------------------, VLISTVLIST [title] | | `---------------------------------------------------------------------' Displays the current contents of all active user variables. This command might be useful for debugging purposes by inserting it at strategic points in your macro code. The output of VLIST is redirectable to a file using the ">" or ">>" symbols. ,---------------------------------------------------------------------, WINDOWWINDOW sl,sc,el,ec,fc,bc,blc[,bt] [title] | | `---------------------------------------------------------------------' Displays a general purpose text window on the screen using the colors and coordinates provided. The contents of the screen behind the window along with most of the current video attributes (colors, cursor position, etc...) are saved on dCOM's windowing stack before the window is displayed. When you are done using the window, they are 'popped' off using the RSTWIN command. With RSTWIN you have the option of restoring the window back to its previous contents, or leaving the window on the screen and only restoring the window stack pointer (RSTWIN's /N switch). 74 Macro Language - Macro Command Reference ---------------------------------------------------------------------- Multiple windows can be nested on the screen for as much as the size of the window stack allows. A WINDOW is considered open until a matching RSTWIN is encountered. When a window is open, screen writes are performed directly using dCOM's screen driver instead of using MS-DOS calls. Any text echoed to the screen while a window is open will use the active colors (as established by the WINDOW command, or a subsequent COLOR command), and will scroll automatically within the boundaries of the window. If the cursor is visible, the window will scroll when a line feed causes it to drop on the window's bottom border line, opening a new blank line. If the cursor not visible, the window will not scroll until an attempt is made to echo text to the window while the cursor is on the window's bottom border line. When a window is initially opened, the cursor is disabled. It could then be enabled using one of two undocumented commands. When the window is closed with RSTWIN, the cursor is restored to its original position before the window was opened. The size of dCOM's windowing stack defaults to a value that should prove sufficient for most windowing operations. It can hold a little over one full screen of saved windows (i.e. fourteen 5 line x 30 column windows). If you receive a Windowing Stack Overflow error when trying to use this command, check to ensure that you are properly popping windows off the window stack with the RSTWIN command. If so, you may need to increase the size of the windowing stack by using dCOM's /W command line switch (described in dCOM's file handler documentation). sl sl The window start line (1..25) sc sc The window start column (1..80) el el The window end line (1..25) ec ec The window end column (1..80) fc fc The active foreground color of the window (0..15) bc bc The active background color of the window (0..7) blc blc The foreground color of the border lines (0..15) bt bt An optional border line-type override (1..4). 1 = single- width lines, 2 = double-width lines, 3 = solid lines, 4 = no border lines. If this value isn't specified, the window uses whatever line type the file handler is configured for. title title Optional text for the window's title. If this parameter is used, the text is displayed centered in the window, one line below the top border, and another single-width line is drawn below the text. The text is displayed using the window's foreground and background colors. See also: RSTWIN, %W1, %W2, %W3, %W4 75 Macro Language - Macro Command Reference ---------------------------------------------------------------------- Example: WINDOW 2,3,24,77,14,1,11,1 CONFIG.SYS ;;DISP WINDOW ON THE SCN COLOR 15,1 ;;CHG COLOR FOR BODY TEXT OPEN #1,C:\CONFIG.SYS ;;OPEN CONFIG.SYS FILE DO WHILE NOT EOF (1) ;;WHILE NOT END OF FILE READLN #1,%TEXT ;; %TEXT=NEXT LINE ECHO %TEXT ;; DISPLAY IT ENDDO ;;CYCLE BACK IF NOT EOF CLOSE #1 ;;CLOSE CONFIG.SYS KEYWAIT ;;WAIT FOR ANY KEY RSTWIN ;;REMOVE THE WINDOW ,---------------------------------------------------------------------, WRITEWRITE [#]filenumber[,text] | | `---------------------------------------------------------------------' Writes a line of text to the file associated with the file number specified. The file number specified must first have been opened with either a CREATE or OPEN command. If the file was opened with the OPEN command, either its /A or /W switch must have been used so that write access will be allowed. The text written can be made up of any combination of literal text and/or user variables. A Carriage Return/Line-Feed sequence is always appended to the text written. The output text starts with the first significant character following the file number (other than a trailing comma). Tabs and spaces are not considered significant. If the file being written is to be read in the future with the READ command using multiple fields, express the output text using commas to separate the fields being written. See also: CREATE, OPEN, READ, READLN, WRITEB, CLOSE, %FP Example: %VAR1=Field 1 ;;%VAR1="Field 1" %VAR2=Field 2 ;;%VAR2="Field 2" %VAR3=Field 3 ;;%VAR3="Field 3" CREATE #1,C:\TESTDAT.TXT ;;CREATE C:\TESTDAT.TXT WRITE #1,%VAR1,%VAR2,%VAR3 ;;WRITE THE FIELDS CLOSE #1 ;;CLOSE THE FILE ,---------------------------------------------------------------------, WRITEBWRITEB [#]filenumber[,text] | | `---------------------------------------------------------------------' Writes text to the file associated with the file number specified. 76 Macro Language - Macro Command Reference ---------------------------------------------------------------------- The file number specified must first have been opened with either a CREATE or OPEN command. If the file was opened with the OPEN command, either its /A or /W switch must have been used so that write access will be allowed. The text written can be made up of any combination of literal text and/or user variables. Unlike the WRITE command, a Carriage Return/Line-Feed sequence is not appended to the text written. The output text starts with the first significant character following the file number (other than a trailing comma). Tabs and spaces are not considered significant. This command would normally be used for writing to binary files instead of text files. See also: CREATE, OPEN, READB, WRITE, CLOSE, %FP 77 Macro Language - Variables ---------------------------------------------------------------------- Macro VariablesMacro Variables Macro variables are the heart of building intelligence into your macro keys. They allow you to build macros that react to what file is currently selected or tagged files, save working values, do arithmetic, and so on.... If the file handler is active and a macro key is invoked while the currently selected file is named "MYLIFE.DOC", consider the following example of how the %FN and %FE variables would expand: Macro Text Becomes ,------------, ,-----------------, | word %fn |----» | word MYLIFE | `------------' `-----------------' ,------------, ,-----------------, | wp %fe |----» | wp MYLIFE.DOC | `------------' `-----------------' Any type of macro variable always begins with a "%" (percent) character. Whenever a percent character is encountered, the macro engine expects it to be the start of a variable and will attempt to expand it into something. The only exception is when two percent characters are used back-to-back, in this case no variable expansion is attempted, and only one of the percent characters is actually passed through. If you are running a program and need to pass a percent character through to the program, be sure to use two percent characters in sequence. Macro variable names are not case sensitive (as usual). You can define a user variable in upper case and refer to it later on in lower case. Macro variable names are not recognized unless they are terminated by an invalid name character. An invalid name character is anything that's not alphabetical except the underscore. This eliminates the opportunity for mis-evaluation of variable names which might not yet be defined. For instance, if a variable called %TEST had been defined, trying to access it as %TESTING will not work to produce the value of %TEST+"ING" - it will return a null value unless %TESTING has also been defined. If you need to express a variable name directly followed by alphabetical characters, enclose the variable name in parenthesis (in which case both of the parenthesis will be dropped). For example, "(%TEST)ING will result in the value of %TEST+"ING". If you actually want to use a variable inside parenthesis, use two sets of parenthesis on both sides. 78 Macro Language - Variables ---------------------------------------------------------------------- There are three types of macro variables; user, system, and equates. User variables and system variables are described in the upcoming sections. Equate variables are described under the [EQUATES] section on page 22. User variables are variables you can assign values to during macro execution, which can be changed again and again as macro execution progresses. System variables are internal variables that contain values which return information internal to dCOM. You can't directly modify the value of a system variable. Some system variables can also be used as functions to return a value based on the parameters you supply it. For instance, one system variable, %SS(), returns a substring of the string passed to it. Equate variables are static variables which can only be set once. They are useful for defining the value of something once at the start of a macro, so you don't have to go searching through the macro at a later point if you want to change it. 79 Macro Language - User Variables ---------------------------------------------------------------------- User VariablesUser Variables User variables are variables created and assigned during macro execution. Their names can be whatever you feel like calling them within a certain set of rules. You can use as many different user variables as necessity dictates. dCOM maintains a special memory buffer to hold user variables. The total size of all user variable names and their current values can total as large as 64k. There are two types of user variables, temporary and permanent. A temporary user variable lives as long as the macro engine is executing macro code. The minute it stops and control returns to either the menu mode or file handler, all temporary user variables are deleted from the memory buffer. A permanent user variable remains in memory for as long as dCOM is running. Permanent user variables begin with a "%@" sequence and are good for such things as holding configuration options in a menu system, or anything that needs to 'live' for a long period of time. The use of permanent variables should be very judicious. Once set, they consume memory across the duration of time that dCOM is active (unless expanded memory is present). Temporary user variables begin with just a percent character. They are good for holding keyboard responses, interim working values, etc... Since they are automatically deleted from memory when macro execution terminates, most of what you do with user variables should be done using temporary variables. User variable names are limited to the characters of A..Z, 0..9, and the underscore. user variables cannot be named the same as a system variable. If this happens accidentally, an Illegal Variable Name error will occur during runtime. Example usages are: ,---------------------------------------------------------------------, TEMPORARY VARIABLES PERMANENT VARIABLES | | |---------------------------------------------------------------------| %DATA_DIR %DATA_DIR=C:\DATA %@MENU_COLS%@MENU_COLS=15,1,11,14,2 | | | GETW %FILENAME%FILENAME,13,Enter File: MENUCOLOR %@MENU_COLS%@MENU_COLS | | | ADD %TOTAL%TOTAL,100 %@LOGIN_TIME%@LOGIN_TIME=%TI | | | `---------------------------------------------------------------------' For debugging purposes, a macro command called VLIST is provided, which can be imbedded at strategic points in macro code so you can view the current values of all user variables. 80 Macro Language - User Variables ---------------------------------------------------------------------- Using User Variables as ArraysUsing User Variables as Arrays User variables can be used in a rudimentary form as an array by following the variable name with a pair of square brackets that enclose the index. This is not a true array logic though where only one variable is dimensioned. Each array element is actually defined individually as a separate user variable. There is no way to get a count of variables that have been defined as array elements in this fashion, like you could with a high level language. You must manage that yourself using another variable. Spaces used inside the square brackets are significant. If you set a variable like this; "%TEST[ 2 ]", you must reference it like that in all other parts of the macro definition. This capability, though limited, can still be quite useful. For example: ,---------------------------------------------------------------------, [F1] ARRAY EXAMPLE ;;TITLE LINE AND SWITCHES | | %TEST[1]=Testing One ;;SET 1ST ARRAY ELEMENT | | %TEST[2]=Testing Two ;;SET 2ND ARRAY ELEMENT | | %MAXINDEX=2 ;;SET MAX ARRAYS DEFINED | | %CNT=0 ;;RESET COUNTER | | DO WHILE %CNT<%MAXINDEX ;;DO WHILE CNT .LT. ELEMENTS | | ADD %CNT,1 ;; INCREMENT THE COUNTER | | ECHO Array %CNT: %TEST[%CNT] ;; DISPLAY CURRENT ELEMENT | | ENDDO ;;END OF DO WHILE BLOCK | | `---------------------------------------------------------------------' Indirect AssignmentsIndirect Assignments User variables can also be set (assigned) indirectly. Indirectly means that the name of the variable being set is determined by the value of another variable. This is done by enclosing the variable being set in parenthesis. For example: ,---------------------------------------------------------------------, %TEST1=%%TEST2 ;; %TEST1 = "%TEST2" | | (%TEST1)=Testing ;; %TEST2 = "Testing" | | `---------------------------------------------------------------------' 81 Macro Language - System Variables ---------------------------------------------------------------------- System VariablesSystem Variables System variables are not variables you can set with a value, at least not directly. They are variables which return items of information that you may want to test on, or use as part of a command to pass to another program. For instance, %FE returns the name of the currently selected file if the file handler is active, and %TI returns the current time. A few of the variables in this section aren't really variables, but are more like flags. When you use them like a variable they don't expand into anything, instead, they set an internal flag in the macro engine. For example, the %XM system variable doesn't return any value, what it does is it tells dCOM to swap itself out to expanded memory or disk the next time it runs an external program. Another example is %W (this is the only single character system variable by the way), which tells dCOM to display the pause message when the macro key terminates (sort of like using the /W title line switch, but you can use it conditionally). System Variable IndexSystem Variable Index %(###)%(###) Untypeable Character................................84 %[var]%[var] Environment Variable................................84 %var%%var% Environment Variable................................84 %AT()%AT() Search String Function..............................85 %C1..%C3%C1..%C3 Miscellaneous Counters..............................85 %CC%CC Current Cursor Column...............................86 %CD()%CD() Current Directory...................................86 %CL%CL Current Cursor Line.................................86 %DD%DD Default Drive.......................................86 %DE%DE Current DO Filename and Extension...................87 %DF()%DF() Date of File........................................86 %DN%DN Current DO Filename (no extension)..................87 %DP%DP dCOM's Home Directory (path)........................87 %DS%DS Current DO File Size................................87 %DT%DT Current System Date.................................87 %DV%DV dCOM's Version Number...............................88 %DW%DW Day of Week.........................................88 %EL%EL Last Error Level....................................88 %ET%ET Error Text in an Error Handler......................88 %EX()%EX() Recursive Expansion Function........................89 %FA()%FA() File Attributes.....................................89 %FC()%FC() Format with Commas Function.........................90 %FD()%FD() Free Disk Space on a Drive..........................90 %FE%FE Currently Selected Filename and Extension...........90 %FM%FM Free Memory.........................................90 82 Macro Language - System Variables ---------------------------------------------------------------------- %FN%FN Currently Selected Filename (no extension)..........90 %FP()%FP() Current File Position of an Open File...............91 %KB%KB Current Keyboard Character..........................91 %LC()%LC() Convert to Lower Case Function......................91 %LD%LD Login Drive (1st Network Drive).....................92 %LE%LE Error Line Number in an Error Handler...............92 %LN%LN Login Name (dCOM's Access Control System)...........92 %MM%MM Memory Mode Active Flag.............................92 %MY%MY Month of Year.......................................92 %OD%OD Original Drive Macro Ran From.......................93 %OS%OS Original Subdirectory Macro Ran From................93 %P1..%P9%P1..%P9 Parameters Passed to a Subroutine...................93 %RJ()%RJ() Right Justifies a String............................93 %RT()%RT() Search String Function (from right to left).........94 %SC%SC Selection Count from SELECT.........................94 %SE%SE Selected Filename & Extension from SELECT...........95 %SF()%SF() Size of File........................................94 %SL()%SL() String Length Function..............................94 %SN%SN Selected Filename (no extension) from SELECT........95 %SP%SP Path of Selected File from SELECT /P................95 %SS()%SS() Substring Function..................................95 %TC%TC Count of Tagged Files...............................96 %TD()%TD() Total Disk Space on Drive...........................96 %TE%TE Tagged Filename and Extension in LOOP...............96 %TI%TI Current System Time.................................97 %TL()%TL() Trim String From Left Function......................97 %TN%TN Tagged Filename (no extension) in LOOP..............96 %TR()%TR() Trim String From Right Function.....................97 %UC()%UC() Convert to Upper Case Function......................97 %VL()%VL() Volume Label of Drive...............................97 %W%W Set Pause Flag When Macro Terminates Flag...........97 %W1..%W4%W1..%W4 Current dimensions of WINDOW........................98 %WD()%WD() Returns a Binary Word Using Numeric Text............98 %WT()%WT() Returns Numeric Text Using a Binary Word............98 %XC()%XC() Repeat Character Function...........................99 %XM%XM Extra Memory When Running Program Flag..............99 83 Macro Language - System Variable Reference ---------------------------------------------------------------------- System Variable ReferenceSystem Variable Reference ,---------------------------------------------------------------------, %(###)%(###) | | `---------------------------------------------------------------------' Generates an untypeable ASCII character. This could be handy for sending printer codes, etc.... There is no requirement to provide three digits if only one or two are needed. Other user or system variables may be embedded inside this variable. See also: %WD Example: [F1] COMPRESSED PITCH ;;TITLE LINE AND SWITCHES PRINTSTR %(15)%(15) ;;SET EPSON PRINTER TO COMPRESSED ,---------------------------------------------------------------------, %[var]%[var] | | `---------------------------------------------------------------------' Returns the current contents of an environment variable. This method of accessing an environment variable is preferred over the method described next (%var%), because its syntax is potentially less confusing to the macro engine, and it also reliably returns a null value if the environment variable is undefined. You may often need to access the contents of an environment variable so you can save it before modifying it, or for some other reason. See also: %var% Example: [F1] MS-WORD ;;TITLE LINE AND SWITCHES %OLDPATH=%[PATH]%[PATH] ;;SAVE CURRENT PATH IN %OLDPATH SET PATH=C:\WORD;%[PATH]%[PATH] ;;REVISE IT TO INCLUDE C:\WORD WORD ;;RUN MS-WORD FROM PATH SET PATH=%OLDPATH ;;RESTORE PATH TO ORIG CONTENTS ,---------------------------------------------------------------------, %var%%var% | | `---------------------------------------------------------------------' Returns the current contents of an environment variable. 84 Macro Language - System Variable Reference ---------------------------------------------------------------------- This method of accessing an environment variable has been replaced by the %[var] method, but is still provided for backward macro compatibility and batch file compatibility. Use of this method to access an environment variable should be changed to the "%[var]" method wherever possible. The reason why is that if any part of the environment variable expressed matches the name of a user variable, the user variable will be returned first. For example, if %PA were set as a user variable, trying to access the path as %PATH% would return the value of %PA+"TH". See also: %[var] ,---------------------------------------------------------------------, %AT%AT(searchstring,sourcestring[,start]) | | `---------------------------------------------------------------------' Searches the "sourcestring" for "searchstring" starting at position "start". This variable provides a mechanism to search a string for a substring. If the substring is found, its starting position is returned, otherwise zero is returned. The search performed is case-insensitive (what's new), moving from left to right. If the starting position isn't given, the search begins with the first character of the "sourcestring". See also: %SS, %RT Example: ECHO %AT(STING,TESTING) ;;DISPLAYS A "2" ,---------------------------------------------------------------------, %C1..%C3%C1..%C3 | | `---------------------------------------------------------------------' The use of these variables is rather advanced and obscure. They are described mainly in the interest of indicating all options available. %C1 and %C2 indicate the number of times a [FILEAUTO] or [MENUAUTO] (respectively) have run since macro execution started. %C3 returns the number of times the RUNMACRO command has been executed since macro execution started. 85 Macro Language - System Variable Reference ---------------------------------------------------------------------- ,---------------------------------------------------------------------, %CC%CC | | `---------------------------------------------------------------------' Returns the current cursor column. If this variable is accessed before the screen is initially cleared, an erroneous value will be returned. See also: %CL ,---------------------------------------------------------------------, %CD%CD | | %CD%CD(d:) | | `---------------------------------------------------------------------' Returns the current directory of the default drive (i.e. "\word", or "\"), or the current directory of the drive specified. A trailing backslash should always be used with this variable when combining it with other variables or text to form a complete pathspec. If the current directory happens to be the root directory, the macro engine will automatically ensure that two backslashes aren't produced by the combination of "%CD\text". See also: %OS ,---------------------------------------------------------------------, %CL%CL | | `---------------------------------------------------------------------' Returns the current cursor line. If this variable is accessed before the screen is initially cleared, an erroneous value will be returned. See also: %CC ,---------------------------------------------------------------------, %DD%DD | | `---------------------------------------------------------------------' Returns the current default drive (i.e. "C:"). See also: %LD, %OD ,---------------------------------------------------------------------, %DF%DF([d:][path]filename) | | `---------------------------------------------------------------------' Returns the date and time stamp of a file as: "MM-DD-YY HH:MM:SS". If you are only interested in just date or time, use %SS() to isolate that portion. 86 Macro Language - System Variable Reference ---------------------------------------------------------------------- See also: %SF ,---------------------------------------------------------------------, %DN%DN | | %DE%DE | | `---------------------------------------------------------------------' Within a DO loop, expands into the current iteration's filename or filename and extension (respectively). Using these variables in a DO block lets you build macro keys to handle multiple files that have something in common (i.e. .BAK files). See also: DO, %DS ,---------------------------------------------------------------------, %DP%DP | | `---------------------------------------------------------------------' Returns the drive and path from which dCOM was run (the Home Directory). A trailing backslash should always be used with this variable when combining it with other variables or text to form a complete pathspec. If dCOM's home directory happens to be the root directory, the macro engine will automatically ensure that two backslashes aren't produced by the combination of "%DP\text". See also: %CD, %DV, %OS ,---------------------------------------------------------------------, %DS%DS | | `---------------------------------------------------------------------' Within a DO loop, expands into the current iteration's filesize. See also: DO, %DE, %DN ,---------------------------------------------------------------------, %DT%DT | | `---------------------------------------------------------------------' Returns the current system date in the format: YY-MM-DD. See also: %DF, %TI 87 Macro Language - System Variable Reference ---------------------------------------------------------------------- ,---------------------------------------------------------------------, %DV%DV | | `---------------------------------------------------------------------' Returns dCOM's version number as text in integer form without a period separating the major version number from the minor version number. This allows it to be tested in an IF statement using less- than or greater-than operators. See also: %DP Example: IF %DV<362 THEN ;;IF DCOM'S VER IS TOO OLD BEEP ;; BEEP SPEAKER MENU dCOM Ver is Too Old ;; DISPLAY ERROR MESSAGE .Press Return to Continue ;; USING MENU COMMAND EXIT ;; TERMINATE MACRO EXECUTION ENDIF ;;END OF IF BLOCK ,---------------------------------------------------------------------, %DW%DW | | `---------------------------------------------------------------------' Returns the day of week (Monday, Tuesday, etc...). See also: %MY ,---------------------------------------------------------------------, %EL%EL | | `---------------------------------------------------------------------' Returns the error level returned by the last program executed. This variable is also updated by several macro commands (i.e. QFORMAT), and it also holds the macro internal error number if an error handling routine is called because of an ONERRORGOTO trap. See also: %ET, %LE, ONERRORGOTO ,---------------------------------------------------------------------, %ET%ET | | `---------------------------------------------------------------------' If an error handling routine is active because of an ONERRORGOTO trap, this variable returns the error text describing the actual error that occurred. See also: %EL, %LE, ONERRORGOTO 88 Macro Language - System Variable Reference ---------------------------------------------------------------------- ,---------------------------------------------------------------------, %EX%EX(text) | | `---------------------------------------------------------------------' Performs a secondary recursive expansion on the text passed as the parameter. This allows a macro variable to contain the name of another macro variable, and have the second macro variable expanded. This might be useful for something like imbedding macro variables in a text file and having them expanded when displayed. Example: ;; Text Displayed ;;------------------------------ %TEXT=Today's Date: %%DT ;; <nothing> ECHO %TEXT ;; Today's Date: %DT ECHO %EX(%TEXT) ;; Today's Date: 07-17-99 ,---------------------------------------------------------------------, %FA%FA | | %FA%FA([d:][path]filename) | | `---------------------------------------------------------------------' Returns the attributes of a file or directory. If the filespec parameter isn't given, the attributes of the file handler's currently selected file or directory are returned. This variable always returns a five character string with each position representing whether a particular flag is set. They are defined as follows: A---- Archive -D--- Directory --S-- System ---H- Hidden ----R Read-Only Since its possible for more than one attribute to be set simultaneously, its not a good idea to be testing on any one of these values explicitly. Instead, use the %AT() function to search for the attribute you are interested in. See also: %SF, %DF 89 Macro Language - System Variable Reference ---------------------------------------------------------------------- Example: IF %AT(D,%FA)>0 THEN ;;IF CURRENTLY SEL'D IS A DIR BEEP ;; BEEP SPEAKER MENU Macro Won't Work on Dirs ;; DISPLAY ERROR MESSAGE .Press Return to Continue ;; USING MENU COMMAND EXIT ;; TERMINATE MACRO EXECUTION ENDIF ;;END OF IF BLOCK ,---------------------------------------------------------------------, %FC%FC(string) | | `---------------------------------------------------------------------' Returns a string formatted with commas inserted every 3 characters from the right. Normally the string would be a numeric variable, but %FC doesn't particularly care whether the parameter given is actually a number. Example: ECHO %FC(%TD(C:)) ;;DISPLAY TOTAL DISK SPACE ON C: ,---------------------------------------------------------------------, %FD%FD | | %FD%FD(d:) | | `---------------------------------------------------------------------' Returns the free disk space of the default drive, or the free disk space of the drive specified. See also: %TD, %VL ,---------------------------------------------------------------------, %FM%FM | | `---------------------------------------------------------------------' Returns the amount of free memory available to external programs. The algorithm used to calculate this value is less extensive than the one used in the file handler, so its value may be off by 16 bytes or so here or there. %FM can't and doesn't account for the extra memory that would be released if a program is run with %XM active. ,---------------------------------------------------------------------, %FN%FN | | %FE%FE | | `---------------------------------------------------------------------' Expands into the currently selected filename or the currently selected filename and its extension (respectively). 90 Macro Language - System Variable Reference ---------------------------------------------------------------------- A runtime error will result if these variables are used in a macro definition that is executed while the menu mode is active (/M command line switch). Using these variables in a macro command lets you build your own point-n-shoot macro commands. See also: %TN, %TE ,---------------------------------------------------------------------, %FP%FP([#]filenumber) | | `---------------------------------------------------------------------' Returns the current file position pointer of a file using the file number that was opened with OPEN or CREATE. ,---------------------------------------------------------------------, %KB%KB | | `---------------------------------------------------------------------' Returns a keyboard character if one is waiting in the keyboard buffer. If no keyboard character is waiting, a value of %(255) is returned. If the keyboard character waiting is an ASCII 0 (used as a escape character when some extended keys like the function keys are pressed), it will be translated to a %(254). Normally you set a user variable with the value of %KB, and then perform tests on the user variable. This is because whenever %KB is referenced and a keyboard character is waiting, the character is then pulled out of the keyboard queue. An immediate subsequent reference to %KB to perform another test will not see the same character. This is OK if you only need to test once on its value and then loop back if false, but multiple tests designed to react to different keys will need a way to test more than once on a single character typed. Example: [F1] WAIT FOR ESC OR RET ;;TITLE LINE AND SWITCHES %KEY= ;;ENSURE %KEY IS RESET DO WHILE %KEY<>%(27) .AND. %KEY<>%(13) ;;DO WHILE NOT ESC OR RET %KEY=%KB ;; %KEY=POSSIBLE KEYPRESS ENDDO ;;LOOP IF NOT ESC OR RET ,---------------------------------------------------------------------, %LC%LC(string) | | `---------------------------------------------------------------------' Returns the string converted to lower case. 91 Macro Language - System Variable Reference ---------------------------------------------------------------------- See also: %UC ,---------------------------------------------------------------------, %LD%LD | | `---------------------------------------------------------------------' Returns the first remote drive found. On a Novell network, this will be the login drive if the user is not currently logged in. If no remote drives are found, %LD returns null. ,---------------------------------------------------------------------, %LE%LE | | `---------------------------------------------------------------------' If an error handling routine is active because of an ONERRORGOTO trap, this variable returns the error line number in the souce macro file. This value is unreliable if the error occured during execution of macro code that was imported with an INCLUDE command. See also: %EL, %ET, ONERRORGOTO ,---------------------------------------------------------------------, %LN%LN | | `---------------------------------------------------------------------' Returns the current user's login name under the access control system. If the access control system isn't active, the current user is considered the supervisor. ,---------------------------------------------------------------------, %MM%MM | | `---------------------------------------------------------------------' Returns a bolean value indicating whether the menu mode is active. If the menu mode is active, a non-zero value is returned, otherwise zero is returned. See also: MACROMENU ,---------------------------------------------------------------------, %MY%MY | | `---------------------------------------------------------------------' Returns the month of year (January, February, etc...). See also: %DW 92 Macro Language - System Variable Reference ---------------------------------------------------------------------- ,---------------------------------------------------------------------, %OD%OD | | `---------------------------------------------------------------------' Returns the original drive which was the default when the macro key was first invoked. See also: %DD ,---------------------------------------------------------------------, %OS%OS | | `---------------------------------------------------------------------' Returns the original subdirectory which was the current directory when the macro key was first invoked. A trailing backslash should always be used with this variable when combining it with other variables or text to form a complete pathspec. If the original subdirectory happens to be the root directory, the macro engine will automatically ensure that two backslashes aren't produced by say the combination of "%OD%OS\%FE" (the full pathspec to the originally selected file). See also: %CD ,---------------------------------------------------------------------, %P1..%P9%P1..%P9 | | `---------------------------------------------------------------------' Returns the value of a parameter passed to the current subroutine or macro file. Both the GOSUB and GOSUBMF commands allow arguments to be passed to the called procedure or macro file using a parameter list surrounded in parenthesis. Inside the called procedure or macro file the parameters are accessed using %P1..%P9 (%P1 = the first parameter, %P2 = the second, and so on...). The values of %P1..%P9 change dynamically with each level of nesting involved. See also: GOSUB, GOSUBMF ,---------------------------------------------------------------------, %RJ%RJ(string,length) | | `---------------------------------------------------------------------' Returns the string right justified within the length specified. Spaces are used to pad the left side of the string in order to return a string equal to the length given. If the string specified is longer than the length specified, the full length of the string is returned. 93 Macro Language - System Variable Reference ---------------------------------------------------------------------- See also: %FC, %SL Example: %VAR1=1234 ;;%VAR=1234 ECHO %RJ(%VAR1,10) ;;DISPLAYS " 1234" ECHO %RJ(%FC(%VAR1),10) ;;DISPLAYS " 1,234" ,---------------------------------------------------------------------, %RT%RT(searchstring,sourcestring) | | `---------------------------------------------------------------------' Searches for "searchstring" in "sourcestring", starting at the end of "sourcestring". This variable provides a mechanism to search a string for a substring. If the substring is found, its starting position is returned, otherwise zero is returned. The search performed is case-insensitive, moving from right to left. See also: %AT, %SS Example: ECHO %RT(T,TESTING) ;;DISPLAYS A "4" ,---------------------------------------------------------------------, %SC%SC | | `---------------------------------------------------------------------' Returns the count of files found with the last SELECT command. See also: %SN, %SE, %SP, SELECT ,---------------------------------------------------------------------, %SF%SF([d:][path]filename) | | `---------------------------------------------------------------------' Returns the size of a file. See also: %DF ,---------------------------------------------------------------------, %SL%SL(string) | | `---------------------------------------------------------------------' Returns the length of "string". See also: %AT, %RT, %SS 94 Macro Language - System Variable Reference ---------------------------------------------------------------------- Examples: %TEXT=TESTING ;;%TEXT="TESTING" %LEN=%SL(%TEXT) ;;%LEN=7 %LEN=%SL(%SS(%TEXT,3)) ;;%LEN=5 ,---------------------------------------------------------------------, %SN%SN | | %SE%SE | | `---------------------------------------------------------------------' Expands into the filename or filename and its extension (respectively) that was picked from the last SELECT menu. See also: %SC, %SP, SELECT ,---------------------------------------------------------------------, %SP%SP | | `---------------------------------------------------------------------' When the SELECT command is used with a /P switch, %SP returns the full path (drive and directory) from which the file (%SN or %SE) was selected. A trailing backslash should always be used with this variable when combining it with %SN or %SE to form the full pathspec. If the path selected happened to be the root directory, the macro engine will automatically ensure that two backslashes aren't produced by the combination of "%SP\%SE". See also: %SN, %SE, SELECT ,---------------------------------------------------------------------, %SS%SS(string,start[,length]) | | `---------------------------------------------------------------------' Returns a substring of "string" starting at position "start" for "length" characters. If the length parameter is omitted, the remainder of the string beginning at the start position is returned. If the length is specified, but it plus the starting position exceed the length of "string", only the remaining valid characters are returned. See also: %AT, %RT, %SL 95 Macro Language - System Variable Reference ---------------------------------------------------------------------- Examples: %TEXT=%SS(TESTING,3) ;;%TEXT="STING" %TEXT=%SS(%TEXT,2,3) ;;%TEXT="TIN" ,---------------------------------------------------------------------, %TC%TC | | `---------------------------------------------------------------------' Returns the count of files currently tagged. A runtime error will result if this variable is used in a macro definition that is executed while the menu mode is active (/M command line switch). See also: %TN, %TE ,---------------------------------------------------------------------, %TD%TD | | %TD%TD(d:) | | `---------------------------------------------------------------------' Returns the total disk space of the default drive, or the total disk space of the drive specified. See also: %FD, %VL ,---------------------------------------------------------------------, %TN%TN | | %TE%TE | | `---------------------------------------------------------------------' Expands into the current iteration's tagged filename, or filename and extension (respectively), within a LOOP block. A runtime error will result if these variables are used in a macro definition that is executed while the menu mode is active (/M command line switch). If no files are tagged in the file handler, these variables will return the currently selected filename (or filename and extension), and the LOOP will only execute for only one iteration. Using these variables in a LOOP block lets you build macro keys that react interactively with the file handler, by processing whatever files are tagged. See also: %FN, %FE, %TC, LOOP 96 Macro Language - System Variable Reference ---------------------------------------------------------------------- ,---------------------------------------------------------------------, %TI%TI | | `---------------------------------------------------------------------' Returns the current system time in the format: HH:MM:SS. See also: %DT ,---------------------------------------------------------------------, %TR%TR(string) | | %TL%TL(string) | | `---------------------------------------------------------------------' Returns the string trimmed of leading or trailing spaces. %TR trims the right edge, %TL trims the left edge. Generally this is not necessary for most macro operations as the macro engine normally does it internally, except for file I/O with the READLN command. See also: %SS ,---------------------------------------------------------------------, %UC%UC(string) | | `---------------------------------------------------------------------' Returns the string converted to upper case. See also: %LC ,---------------------------------------------------------------------, %VL%VL | | %VL%VL(d:) | | `---------------------------------------------------------------------' Returns the volume label of the default drive, or the volume label of the drive specified. See also: %FD, %TD ,---------------------------------------------------------------------, %W%W | | `---------------------------------------------------------------------' This variable is actually a flag that tells dCOM to display a pause (wait) message when the macro terminates. This is the same thing as using the /W title line switch except that %W can be issued conditionally. %W doesn't return anything (its presence in a command line is simply deleted). Leading or trailing spaces surrounding %W are significant though. 97 Macro Language - System Variable Reference ---------------------------------------------------------------------- ,---------------------------------------------------------------------, %W1..%W4%W1..%W4 | | `---------------------------------------------------------------------' Return the current text area dimensions of the active WINDOW (start line, start column, end line, and end column - respectively). If no WINDOW is active, the dimensions of the entire screen are returned. For instance, if you had opened a window using "WINDOW 5,10,20,70...", these variables would return: %W1=6, %W2=12, %W3=19, %W4=69. Note that all of them except %W2 return a value of one increment inside the window specified. The start column (%W2), is automatically adjusted by the WINDOW command to indent two columns to allow for a space to separate the left border from the text echoed inside the window. These variables might be useful in a subroutine that needs to know the boundaries of the active window so it can position the cursor to some location inside the window and display something - and not have to hard-wire the subroutine with the dimensions of the window. See also: WINDOW ,---------------------------------------------------------------------, %WD%WD(numerictext) | | `---------------------------------------------------------------------' Returns a binary word (2 byte) value for the numeric text specified. About the only time you would need the function provided by this variable is if you need to write the value of an integer word to a binary-type file. This is because the macro engine internally retains all user variables as text, whether they contain numeric values or not. In order to express a number as a 2's compliment integer word, this variable is required. If only a byte value is needed, refer to the %(###) variable. See also: %WT, %(###) ,---------------------------------------------------------------------, %WT%WT(wordvalue) | | `---------------------------------------------------------------------' Returns the numeric text value of a binary word integer. The 32-bit value returned is unsigned. About the only time you would need the function provided by this variable is if you read a word value from a file using the READB 98 Macro Language - System Variable Reference ---------------------------------------------------------------------- macro command and need to convert the value to text in order to work with it or display it. This variable performs the opposite function of the %WD variable. See also: %WD ,---------------------------------------------------------------------, %XC%XC(char,length) | | `---------------------------------------------------------------------' Returns a string of "char", "length" characters long. If a string of spaces is desired, the space character must be represented as %(32). This is due to the internal parsing of the parameter list which discards leading and trailing space characters between arguments. This is even more critical in IF statements, where not only will the %XC not expand correctly, but a literal space character might be misconstrued as a delimiter between operands. Where practical, it is more memory efficient to express longer strings using %XC than to represent them literally in macro code. See also: %SS Examples: ECHO %XC(=,5) ;;DISPLAYS A "=====" ECHO %XC(%(32),30) ;;DISPLAYS 30 SPACES ECHO %XC(%(205),80) ;;DRAW A LINE OF "-" ,---------------------------------------------------------------------, %XM%XM | | `---------------------------------------------------------------------' This is a special variable that acts more like a switch. It doesn't return anything (its presence in a command line is simply deleted). Leading or trailing spaces surrounding %XM are significant though. What %XM does is it tells dCOM to swap itself out to expanded memory or disk the next time an external application is run. This effectively reduces dCOM to less than 10k in memory (a small kernel has to remain in memory in order to reload the swapped out code and data). Normally you include this variable on the actual line that runs the program, but its possible to use it several lines before as long as you're sure that the next externally run program is the one you want it to work with. Instead of using this variable however, a text file called XM.SYS can be created in dCOM's home directory that contains the names of 99 Macro Language - System Variable Reference ---------------------------------------------------------------------- programs for which you need the "extra memory". In this file, the program names can be separated by spaces, commas, tabs, or individually per line. If a program name is given without its extension (.COM or .EXE), either one will qualify as a match. When a program is run with the "XM" effect, the background benefits of dCOM are removed until the program terminates. This includes the print spooler, printer redirection, screen saver, screen blanker, alarms, all of the hot keys, etc... (Believe it or not, the 45k that dCOM normally leaves behind when it runs a program is there for a reason.) Another side effect is that any TSR's currently loaded in dCOM's memory are automatically ejected. Reducing dCOM down to a 10k image does no good if a TSR is sitting directly above the released memory. And, if the application itself loaded a TSR (or was a TSR), it will quietly be given the boot as well when control returns to dCOM - because dCOM needs to reload itself back into the same memory it was in to start with. When a program is run with the "XM" effect, dCOM will first attempt to save the swap image to expanded memory. If expanded memory isn't present, it will save it to a temporary file on disk. Where the temporary file is saved depends on several things. If dCOM's /TMP command line switch was specified, it will take precedence and the temp file is always stored there. If the /TMP command line switch wasn't specified, dCOM will react to on-the-fly changes to the TEMP environment variable (the same environment variable Windows uses) and place the temp file there. If neither are defined, the temp file is stored in dCOM's home directory. If dCOM is run from a network drive and the user doesn't have Write and Create privileges to dCOM's home directory, and expanded memory isn't present - you should ensure that either the /TMP command line switch, or the TEMP environment variable point to a directory where the user does have Create, Write, Read, and Erase privileges - or the "XM" effect will silently just not work. 100 Macro Language - Examples ---------------------------------------------------------------------- Macro ExamplesMacro Examples The following examples are provided to help illustrate some macro capabilities. They are not meant to in any way imply an endorsement or advocate the use of one brand of software over another. When considering the examples, a certain amount of interpretation, adjustment, and/or substitution may be required to suit your own situations. Each of the macro examples uses the F1 key for its title line definition. If you implement any of the examples, you will probably need to change F1 to a key that hasn't already been defined. Also, every macro line has been commented with an explanation of what the line does. If you use these examples as a basis to build some of your macro keys, typing in the comments is purely optional. Changing to a Frequently Used DirectoryChanging to a Frequently Used Directory ,---------------------------------------------------------------------, [F1] CD C:\DOCS ;;TITLE LINE AND SWITCHES | | CDD C:\DOCS ;;CHANGE DRIVE & DIRS | | `---------------------------------------------------------------------' This example changes drives and subdirectories to C:\DOCS. Even something as simple as this can prove to be quite a time saver if you have a reason to frequently visit particular subdirectories. Another variation along the same lines would be to use a macro key to just log a new drive. This would be done by replacing "CDD C:\DOCS" with something like "A:". Running a Program - In Its Own DirectoryRunning a Program - In Its Own Directory ,---------------------------------------------------------------------, [F1] WORDSTAR 6 ;;TITLE LINE AND SWITCHES | | CDD C:\WS6 ;;CHANGE DRIVE & DIRS | | WS ;;RUN WORDSTAR | | CD C:\ ;;CHANGE C: BACK TO ROOT DIR | | CDDO ;;RETURN TO ORIG DRIVE & DIR | | `---------------------------------------------------------------------' This example just runs Wordstar, but it typifies the basic "shell" of how a macro would look that runs programs. Note that we took the extra precaution of changing drives and directories with the "CDD" macro command. If all we did was a "CD \WS6", the macro wouldn't work properly if the current drive wasn't drive C:. Also, after Wordstar 101 Macro Language - Examples ---------------------------------------------------------------------- exits, the current directory of drive C: is arbitrarily changed back to its root directory, and then CDDO changes the default drive and current directory back to whatever was active when the macro key initially ran. If the macro key was initially run while C: was the default drive, the CDDO would immediately nullify the line before that changes C: to the root. In any event, C: won't be left sitting in the \WS6 directory. Running a Program - That Uses TSR'sRunning a Program - That Uses TSR's ,---------------------------------------------------------------------, [F1] WORDSTAR 5/r ;;TITLE LINE AND SWITCHES | | CDD C:\WS5 ;;CHANGE DRIVE & DIRS | | WF ;;LOAD WORD FINDER (A TSR) | | WS ;;RUN WORDSTAR | | CD C:\ ;;CHANGE C: BACK TO ROOT DIR | | CDDO ;;RETURN TO ORIG DRIVE & DIR | | `---------------------------------------------------------------------' This example is a spin-off of the previous example. The difference is that the macro is configured to remove TSR's when it terminates (by using the /R switch on the title line) and also loads Word Finder before running Wordstar. Word Finder is a Thesaurus type TSR program which is useful when used in conjunction with Wordstar, but is normally of little use after you are done working in Wordstar. (Current versions of Wordstar no longer use the Word Finder as a separate program, but the example still applies.) Running a Program - With the Currently Selected FileRunning a Program - With the Currently Selected File ,---------------------------------------------------------------------, [F1] MS-WORD ;;TITLE LINE AND SWITCHES | | PATHADD C:\WORD ;;ADD C:\WORD TO PATH | | WORD %FE ;;RUN WORD WITH SEL'D FILE | | PATHDEL C:\WORD ;;REMOVE C:\WORD FROM PATH | | `---------------------------------------------------------------------' This example runs MS-Word, passing to it the filename of the currently selected file from the file handler. Before running Word though, the macro temporarily adds the path to Word's program files to the MS-DOS PATH. This ensures it will run correctly even if the AUTOEXEC.BAT didn't set a path to Word. If AUTOEXEC.BAT does set a path to MS- Word, you wouldn't want to use the PATHADD and PATHDEL statements because PATHDEL will remove all entries of C:\WORD from the path. 102 Macro Language - Examples ---------------------------------------------------------------------- ,---------------------------------------------------------------------, [F1] MS-WORD ;;TITLE LINE AND SWITCHES | | CDD C:\WORD ;;CHANGE DRIVE & DIRS | | WORD %OD%OS\%FE ;;RUN WORD WITH SEL'D FILE | | CD C:\ ;;CHANGE C: BACK TO ROOT DIR | | CDDO ;;RETURN TO ORIG DRIVE & DIR | | `---------------------------------------------------------------------' This is a variation on the previous example. It changes to the MS- Word program directory and then runs Word, passing to it the full pathspec of the filename that was currently selected when the macro key was invoked. %OD expands into the original drive that was active when the macro key was pressed (i.e. "C:"). %OS expands into the original subdirectory that was active when the macro key was pressed (i.e. "\DOCS"). And %FE expands into the currently selected filename with its extension. This is not a normal approach to running a program however, because if you try to open additional documents while in the program, the current directory will most likely not be in the same directory as when you invoked the macro. It is only provided as an example of how to do it should the occasion arise. Running a Program - Selecting a File FirstRunning a Program - Selecting a File First Often it is desirable to display a menu that allows the user to select from a list of available files or directories before running a program. There are many ways in which this can be done. ,---------------------------------------------------------------------, [F1] HARVARD GRAPHICS ;;TITLE LINE AND SWITCHES | | SELECT C:\HG\*.CHT Pick a Chart/n ;;PROMPT FOR FILE TO USE | | CDD C:\HG ;;CHANGE DRIVE & DIRS | | HG %SE ;;RUN HARVARD W/FILE PICKED | | CD C:\ ;;CHANGE C: BACK TO ROOT DIR | | CDDO ;;RETURN TO ORIG DRIVE & DIR | | `---------------------------------------------------------------------' This is the simplest method of selecting a file before you run something. It assumes that all of the chart files are in Harvard's directory, not off in a separate directory. It first prompts for the user to select a Harvard chart file, then it changes into Harvard's program directory and runs Harvard passing it the filename of the chart picked. But what if you want to pick a file that's in a different directory than where the program's executable files are? So we'll go from one extreme to the other. Lets also say that the files are in a directory 103 Macro Language - Examples ---------------------------------------------------------------------- structure that's categorized using different subdirectories. For example: C:\---DOS |-DCOM |-DOCS-----REPORTS | |-CORES | |-MEMOS | `-MISC `-WORD ,---------------------------------------------------------------------, [F1] MS-WORD ;;TITLE LINE AND SWITCHES | | SELECT C:\DOCS\*.* PICK A DIR/d ;;PROMPT FOR DIR TO USE | | %DIR=%SE ;;%DIR=SELECTED DIR | | SELECT C:\DOC\%DIR\*.DOC FILES/n ;;PROMPT FOR FILE TO USE | | CDD C:\DOCS\%DIR ;;CHANGE DRIVE & DIRS | | WORD %SE ;;RUN WORD WITH THE FILE | | CD C:\ ;;CHANGE C: BACK TO ROOT DIR | | CDDO ;;RETURN TO ORIG DRIVE & DIR | | `---------------------------------------------------------------------' This example first displays a menu of the subdirectories that exist under C:\DOCS. Then, it displays a second menu of all files in that subdirectory which have a .DOC extension. (The reason why the SELECT command is suddenly capable of showing subdirectory names instead of filenames is because of the /D switch.) Then, it runs Microsoft Word with the name of the file selected. In this example we're relying on the PATH to find MS-Word. Running a Program - Selecting a File First (Version II)Running a Program - Selecting a File First (Version II) ,---------------------------------------------------------------------, [F1] MS-WORD ;;TITLE LINE AND SWITCHES | | SELECT C:\DOCS\*.DOC Files/n/p ;;PROMPT FOR FILE TO USE | | PATHADD C:\WORD ;;ADD C:\WORD TO PATH | | CDD %SP ;;CHANGE DRIVE & DIRS | | WORD %SE ;;RUN WORD WITH FILE PICKED | | PATHDEL C:\WORD ;;REMOVE C:\WORD FROM PATH | | CD C:\ ;;CHANGE C: BACK TO ROOT DIR | | CDDO ;;RETURN TO ORIG DRIVE & DIR | | `---------------------------------------------------------------------' This example starts to spruce things up a little. It first displays a menu that allows the user to select a file before running Microsoft Word. Since the /P switch was given with the SELECT command, the user has the option to change drives and/or directories before selecting a file. Next, Word's directory is added to the path, the current directory is changed to the one in which the file was selected (%SP), and then Word is run with the filename picked. If [NEW FILE] was 104 Macro Language - Examples ---------------------------------------------------------------------- picked from the SELECT menu (because the /N switch was used), %SE will return nothing and hence, Word will start with an empty window. So why didn't we change into the C:\DOCS directory before issuing the SELECT command? That way we wouldn't have to spell out the path for SELECT, right? The reason why its normally better to use SELECT commands (with full paths to what you want selected) before you change directories is because if the SELECT menu is escaped, the macro will abort - probably leave you sitting in a different directory than where you were before the macro was invoked. But, with a couple more macro lines we can trap that Escape key.... ,---------------------------------------------------------------------, [F1] MS-WORD ;;TITLE LINE AND SWITCHES | | ONBREAKGOTO ABORT ;;TRAP THE ESCAPE KEY | | CDD C:\DOCS ;;CHANGE DRIVE AND DIRS | | SELECT *.DOC Pick a Document/n ;;PROMPT FOR FILE TO USE | | PATHADD C:\WORD ;;ADD C:\WORD TO PATH | | WORD %SE ;;RUN WORD WITH FILE PICKED | | PATHDEL C:\WORD ;;REMOVE C:\WORD FROM PATH | | :ABORT ;;ESCAPE KEY JUMP POINT | | CD C:\ ;;CHANGE C: BACK TO ROOT DIR | | CDDO ;;RETURN TO ORIG DRIVE & DIR | | `---------------------------------------------------------------------' This example traps the Escape key when the SELECT menu is active. Since we are trapping Escape, its safe to go ahead and change directories first before displaying the SELECT menu. If we didn't trap it, pressing Escape while the SELECT menu is active would abort the macro and leave it in the C:\DOCS directory. Also, since we didn't use the /P option with the SELECT command, the user will not have an option to pick a file in a different directory. Running a Program - Saving Current DirectoryRunning a Program - Saving Current Directory ,---------------------------------------------------------------------, [F1] MS-WORD ;;TITLE LINE AND SWITCHES | | %ORIGDIR=%CD(C:) ;;%ORIGDIR = DRV C:'S CUR DIR | | PATHADD C:\WORD ;;ADD C:\WORD TO THE PATH | | CDD C:\DOCS ;;CHANGE DRIVE & DIRS | | WORD ;;RUN WORD FROM PATH | | CD C:%ORIGDIR ;;RESTORE C: TO ORIG DIR | | PATHDEL C:\WORD ;;REMOVE C:\WORD FROM PATH | | CDDO ;;RETURN TO ORIG DRIVE & DIR | | `---------------------------------------------------------------------' This example goes way out of its way to restore all the current directories to the way they were when the macro key was first 105 Macro Language - Examples ---------------------------------------------------------------------- executed. Normally, when you run a macro key from the same drive that the macro key uses when it changes directories, the CDDO command will take care of restoring it to its original directory. In all of the previous examples we were arbitrarily changing C: back to its root directory in case CDDO was going to restore to a different drive. If you really want to cover all the bases though, this is how you would do it. Additionally, the macro temporarily adds the path to Word's program files to the MS-DOS PATH before running it. This ensures it will run correctly even if the AUTOEXEC.BAT didn't set a path to Word. If AUTOEXEC.BAT does set a path to MS-Word, you wouldn't want to use the PATHADD and PATHDEL statements because PATHDEL will remove all entries of C:\WORD from the path. Running a Program - Menuing Some Options FirstRunning a Program - Menuing Some Options First ,---------------------------------------------------------------------, [F1] FORMAT ;;TITLE LINE AND SWITCHES | | MENU FORMAT,A:,B: ;;DISPLAY DRIVE OPTIONS | | %DRIVE=%MT ;;SAVE IT IN %DRIVE | | MENU FORMAT %DRIVE ;;DISPLAY | | .360K ;; MS-DOS | | .720K ;; FORMAT'S | | .1.2M ;; /F: | | .1.44M ;; OPTIONS | | FORMAT %DRIVE /F:%MT ;;RUN FORMAT WITH SELECTIONS | | `---------------------------------------------------------------------' This example first displays a menu of the possible drives to format. Then, it displays a menu of options that the Format program understands (MS-DOS Version 4.0+) when passed with its /F switch. Then, it runs the MS-DOS Format program to do it (relying on the PATH to find it). Dropping to DosDropping to Dos ,---------------------------------------------------------------------, [F1] DROP TO DOS ;;TITLE LINE AND SWITCHES | | %OLD_PROMPT=%[PROMPT] ;;SAVE PREVIOUS PROMPT VALUE | | SET PROMPT=Type EXIT to Ret to dCOM$_$P$G ;;SET NEW PROMPT | | %[COMSPEC] %XM ;;RUN A COPY OF COMMAND.COM | | SET PROMPT=%OLD_PROMPT ;;RESTORE PREVIOUS PROMPT | | `---------------------------------------------------------------------' This example saves the current value of the PROMPT environment variable and then sets it so that it will display a message indicating how to return to dCOM. Then, it runs another copy of COMMAND.COM by 106 Macro Language - Examples ---------------------------------------------------------------------- using the current value of the COMSPEC environment variable. When the user types 'EXIT', COMMAND.COM terminates (just like exiting any other program), and the previous value of the PROMPT is restored. Also, when COMMAND.COM is run, the %XM system variable is used which tells dCOM to reduce itself to a 10k kernel by swapping itself out of conventional memory to either expanded memory or disk. Normally you don't want to use %XM unless you know the program is running short of memory. If you use %XM, some extra disk activity will occur if expanded memory isn't present, and you'll lose the benefit of having dCOM in the background (i.e. print spooler, printer redirection, screen saver/blanker, etc...). In this case, since the user can or might want to run another significant application from the DOS prompt, using %XM is not such a bad idea. Setting an Epson Printer to CompressedSetting an Epson Printer to Compressed ,---------------------------------------------------------------------, [F1] COMPRESSED PITCH ;;TITLE LINE AND SWITCHES | | PRINTSTR %(15) ;;SEND COMPRESS CODE TO PRN | | `---------------------------------------------------------------------' This example sets an Epson compatible printer into compressed (16 CPI) pitch. Setting an Epson Printer to Pica PitchSetting an Epson Printer to Pica Pitch ,---------------------------------------------------------------------, [F1] PICA PITCH ;;TITLE LINE AND SWITCHES | | PRINTSTR %(18) ;;SEND 10 CPI CODE TO PRN | | `---------------------------------------------------------------------' This example sets an Epson compatible printer to Pica (10 CPI) pitch. This example, along with the one above, suggests how an entire macro file could be used to set various printer pitches or modes. 107 Macro Language - Examples ---------------------------------------------------------------------- Submenuing a Macro KeySubmenuing a Macro Key ,---------------------------------------------------------------------, [F1] WORD PROCESSING ;;TITLE LINE AND SWITCHES | | MENU WORD PROCESSING ;;DISPLAY A MENU WITH | | .MS-Word ;; WORDPROCESSING | | .WordStar ;; CHOICES | | GOTO %MT ;;GOTO LABEL OF TEXT PICKED | | :MS-WORD ;;LABEL FOR GOTO | | CDD C:\MSWORD ;; CHANGE DRIVE & DIRS | | WORD ;; RUN MS-WORD | | CD C:\ ;; CHANGE C: TO ROOT DIR | | CDDO ;; RETURN TO ORIG DRV & DIR | | EXIT ;; AND EXIT THE MACRO | | :WORDSTAR ;;LABEL FOR GOTO | | CDD C:\WS5 ;; CHANGE DRIVE & DIRS | | WS ;; RUN WORDSTAR | | CD C:\ ;; CHANGE C: TO ROOT DIR | | CDDO ;; RETURN TO ORIG DRV & DIR | | EXIT ;; AND EXIT THE MACRO | | `---------------------------------------------------------------------' This example demonstrates the use of the MENU command and how it can be used to pop-up a submenu of choices. Since the MENU command returns the text of the choice selected in %MT, all the macro has to do is issue a GOTO command to jump to a label containing the text selected. This technique could just as easily be applied to getting a Yes or No response from the user before doing something that warrants it. In general though, loading your primary macro file with a lot of text should be avoided because it can accumulate into having a minor effect on free memory (unless expanded memory is present). Another solution might be to build another macro file having these options as separate macro keys, and use the GOSUBMF macro command to call it. 108 Macro Language - Examples ---------------------------------------------------------------------- Archiving Tagged FilesArchiving Tagged Files ,---------------------------------------------------------------------, [F1] ZIP TAGGED FILES/w ;;TITLE LINE AND SWITCHES | | IF %TC=0 THEN ;;IF NO FILES TAGGED | | BEEP ;; BEEP | | MENU Tagged Files Required ;; DISPLAY ERROR MESSAGE | | .Press Return to Continue ;; AS A MENU | | EXIT ;; AND TERMINATE MACRO KEY | | ENDIF ;;END OF IF BLOCK | | GETW %FILE 13 Target ZIP File: ;;GET DEST FILE IN %FILE | | ECHO Building List File ;;DISPLAY WHAT WE'RE DOING | | CREATE #1,C:\ZIPDAT.TMP ;;CREATE TEMPORARY LIST FILE | | :LABEL1 ;;LABEL FOR TAGGED LOOP | | WRITE #1,%TE ;; ADD FILENAME TO LIST | | LOOP LABEL1 ;;LOOP THROUGH TAGGED FILES | | CLOSE #1 ;;CLOSE THE TEMP LIST FILE | | PKZIP -ex -z %FILE @C:\ZIPDAT.TMP ;;CALL PKZIP TO DO IT | | DEL C:\ZIPDAT.TMP ;;DELETE THE TEMP LIST FILE | | `---------------------------------------------------------------------' This example takes all tagged files and compresses them into a .ZIP file. It first tests on whether there are any files tagged. If not, it displays a menu indicating that the macro needs tagged files and then exits. If there are tagged files, the IF block is skipped and the macro asks for a destination ZIP filename. After that, it builds a temporary ASCII file that contains the names of all files that were tagged, and then calls PKZIP to add them to the ZIP filename entered in %FILE. Did you notice how the MENU command can be used as an easy way to pop- up an error message? Also, because of the total length of the text for the menu header and options, it was split between two macro lines by starting the second line with a period. In this case however, it would have been OK to have it all on one line separated with a comma, except then we couldn't have commented it in an aesthetic fashion. 109 Macro Language - Examples ---------------------------------------------------------------------- Converting All .ARC Files to .ZIPConverting All .ARC Files to .ZIP ,---------------------------------------------------------------------, [F1] ARC->ZIP (ALL)/w ;;TITLE LINE AND SWITCHES | | IF EXIST C:\TDIR\*.* THEN ;;IF TEMP DIR ALREADY EXISTS | | BEEP ;; BEEP | | MENU Temp Dir Already Has Files ;; DISPLAY ERROR MESSAGE | | .ABORT ;; 1ST OPTION | | .PROCEED ;; 2ND OPTION | | IF %MS=1 EXIT ;; IF CHOICE IS ABORT, EXIT | | DEL C:\TDIR\*.* /h/n ;; DEL ANYTHING IN \TDIR | | ENDIF ;;END OF IF BLOCK | | | | IF NOT EXIST C:\TDIR MD C:\TDIR ;;MAKE TEMP DIR IF NOT EXIST | | DO *.ARC ;;DO BLOCK FOR .ARC FILES | | ECHO Extracting: %DE; ;; DISPLAY FILE BEING UNARC'D | | PKUNPAK %DE C:\TDIR >NUL ;; UNARC THE FILE | | IF %EL>0 GOTO ERROR ;; IF ERROR UNPACKING, ABORT | | DEL %DE ;; DELETE THE .ARC FILE | | CPOSN ,27 ;; POSITION CURSOR TO COL 27 | | ECHO Zipping: %DN.ZIP; ;; DISPLAY FILE BEING ZIPPED | | PKZIP -m %DN.ZIP C:\TDIR\*.* >NUL ;; ZIP THE UNARCED FILES | | ECHO ;; DROP A LINE | | ENDDO ;;END OF DO BLOCK | | RD C:\TDIR ;;REMOVE THE TEMP DIRECTORY | | EXIT ;; AND EXIT | | :ERROR ;;ERROR JUMP POINT | | BEEP ;; BEEP | | MENU Error %EL Extracting %DE ;; DISPLAY ERROR AS MENU | | .Press Return to Continue ;; USE 1ST OPTION AS PROMPT | | `---------------------------------------------------------------------' This example converts all .ARC files found in the current directory from .ARC format to the more efficient .ZIP format. 110 Macro Language - Examples ---------------------------------------------------------------------- Converting Tagged .ARC Files to .ZIPConverting Tagged .ARC Files to .ZIP ,---------------------------------------------------------------------, [F1] ARC->ZIP (TAGGED)/w ;;TITLE LINE AND SWITCHES | | IF %TC=0 THEN ;;IF NO FILES ARE TAGGED | | BEEP ;; BEEP | | MENU No Files Are Tagged ;; POP-UP A WINDOW THAT SAYS | | .Press Return to Continue ;; NO FILES ARE TAGGED | | EXIT ;; AND EXIT THE MACRO | | ENDIF ;;END OF IF BLOCK | | IF EXIST C:\TDIR\*.* THEN ;;IF C:\TDIR ALREADY EXISTS | | BEEP ;; BEEP | | MENU Temp Dir Already Has Files ;; DISPLAY ERROR MESSAGE | | .ABORT ;; 1ST OPTION | | .PROCEED ;; 2ND OPTION | | IF %MS=1 EXIT ;; IF CHOICE IS ABORT, EXIT | | DEL C:\TDIR\*.* /h/n ;; DEL ANYTHING IN \TDIR | | ENDIF ;;END OF IF BLOCK | | IF NOT EXIST C:\TDIR MD C:\TDIR ;;MAKE TEMP DIR IF NOT EXIST | | :LABEL1 ;;LABEL FOR TAGGED LOOP | | IF %TE<>%TN.ARC THEN ;; IF FILE IS NOT .ARC | | BEEP ;; BEEP | | MENU %TE is Not an ARC File ;; POP-UP A MENU THAT SAYS | | .Press Return to Continue ;; THIS ISN'T AN ARC FILE | | GOTO QUIT ;; AND EXIT THE MACRO | | ENDIF ;; END OF IF BLOCK | | ECHO Extracting: %TE; ;; DISPLAY FILE BEING UNARC'D | | PKUNPAK %TE C:\TDIR >NUL ;; UNARC THE FILE | | IF %EL>0 GOTO ERROR ;; IF ERROR UNPACKING, ABORT | | DEL %TE ;; DELETE THE .ARC FILE | | CPOSN ,27 ;; POSITION CURSOR TO COL 27 | | ECHO Zipping: %TN.ZIP; ;; DISPLAY FILE BEING ZIPPED | | PKZIP -m %TN.ZIP C:\TDIR\*.* >NUL ;; ZIP THE UNARCED FILES | | ECHO ;; DROP A LINE | | LOOP LABEL1 ;;LOOP BACK IF ANOTHER TAG | | :QUIT ;;LABEL FOR EXIT JUMP | | RD C:\TDIR ;;REMOVE THE TEMP DIR | | EXIT ;; AND EXIT | | :ERROR ;;ERROR JUMP POINT | | BEEP ;; BEEP | | MENU Error %EL Extracting %TE ;; DISPLAY ERROR AS MENU | | .Press Return to Continue ;; USE 1ST OPTION AS PROMPT | | `---------------------------------------------------------------------' This example converts all tagged .ARC files to the more efficient .ZIP format. Since the LOOP command and its %TE and %TN variables will work on the selected file if no files are tagged, you could remove the first IF block if you wished to allow that as an option. 111 Macro Language - Examples ---------------------------------------------------------------------- Compiling a Source FileCompiling a Source File ,---------------------------------------------------------------------, [F1] COMPILE SELECTED/w ;;TITLE LINE AND SWITCHES | | :LABEL1 ;;LABEL FOR TAGGED LOOP | | IF %TE<>%TN.ASM THEN ;; IF FILE ISN'T AN .ASM FILE | | BEEP ;; BEEP | | MENU %TE Is Not a .ASM File ;; DISPLAY ERROR MESSAGE | | .Press Return to Continue ;; AS A MENU | | EXIT ;; AND EXIT | | ENDIF ;; END OF IF BLOCK | | ECHO Compiling: %TE ;; ECHO FILE BEING COMPILED | | MASM %TN; ;; COMPILE THE FILE | | IF %EL>0 GOTO ERROR ;; IF AN ERROR GOTO ERROR | | LINK %TN; ;; LINK THE FILE | | IF %EL>0 GOTO ERROR ;; IF AN ERROR GOTO ERROR | | DEL %TN.OBJ ;; DELETE THE .OBJ FILE | | LOOP LABEL1 ;;IF TAGGED FILES LOOP BACK | | EXIT ;;TERMINATE THE MACRO KEY | | :ERROR ;;LABEL FOR ERROR HANDLING | | BEEP ;;BEEP FOR ERRORS | | `---------------------------------------------------------------------' This example compiles and links either tagged files or the selected file. It does this easily because the LOOP command and its %TE and %TN variables automatically work on the selected file if no files are tagged. Most likely though, if someone was going to compile more than one file, they would probably not want to be linking and producing an executable file for every object file compiled. But more likely just compiling the tagged files to object modules and then linking them later in the same macro, or in a different macro key. 112 Macro Language - Examples ---------------------------------------------------------------------- Searching For a FileSearching For a File The following example is a complete macro file. It prompts for a couple parameters and then searches a directory structure for matching files, displaying each one found. This macro file contains all of its macro code under a [FILEAUTO] definition, which activates as soon as the file is loaded into memory. ,---------------------------------------------------------------------, ;=================================================================== | | ; SEARCH.MAC | | ;------------------------------------------------------------------- | | ; Description: | | ; | | ; This macro searches a directory structure for a filemask | | ; and displays entries found. | | ; | | ; Parameters on entry: | | ; %p1 = Default starting search root directory | | ; %p2 = Default filemask | | ; | | ; Notes: | | ; | | ; This macro file should be installed in dCOM's Home | | ; Directory and, can be called by the file handler's | | ; "/" command, or by a local macro key as follows: | | ; | | ; [f1] Search for File | | ; gosubmf search.mac [(search_root_dir,filemask)] | | ; | | ; September, 1991 | | ; Dave Frailey | | ; DAC Micro Systems | | ; | | ;------------------------------------------------------------------- | | [menuauto] ;;just in case things go | | ;; wrong and we stay active | | return ;; up to the point of being | | ;; a menu, this will cause a | | ;; return to the previous | | ;; macro file. | | | | ;------------------------------------------------------------------- | | [fileauto] ;;runs automatically when | | ;; this macro file loads | | | | if %dv<362 then ;;if invalid version of dCOM | | onbreakgoto bad_v_break ;; set escape trap | | beep ;; beep | | 113 Macro Language - Examples ---------------------------------------------------------------------- menu This Macro Requires dCOM Ver 3.62 or Greater | | .Press Return to Continue | | :bad_v_break ;; break trap label | | return ;; return to calling macro | | endif ;;end of if block | | | | %orig_dir=%od%os ;;save orig drive & directory | | if %p1="" ;;if starting dir not passed | | %start_dir=%ss(%orig_dir,1,3) ;; set to deflt drive's root | | else ;;else | | %start_dir=%p1 ;; set it to passed dir | | endif ;;end of if block | | %mask=%p2 ;;%mask = passed search mask | | | | onbreakgoto exit ;;set escape trap | | gosub display_screen ;;display initial screen | | getw %start_dir 24 Starting Dir: ;;get search root dir | | getw %mask 13 Enter Search Mask: ;;get file mask to use | | if %at(.,%mask)=0 ;;if mask doesn't have an ext | | %mask=%mask.??? ;; append wildcard extension | | endif ;;end of if block | | | | onerrorgoto error ;;set error trap | | cdd %start_dir ;;change to starting dir | | gosub search ;;do search | | cposn ,%w2 ;;position to start of window | | ceol ;;clear off last dir disp'd | | gosub display_pause ;;display pause message | | goto exit ;;and exit | | | | :error ;;error jump point | | beep ;; beep | | menu ERROR: %et ;; display error text | | .Press Return to Continue ;; and rest of menu | | :exit ;;exit jump point | | cdd %orig_dir ;; return to orig drive & dir | | return ;; ret to calling macro file | | | | ;------------------------------------------------------------------- | | :SEARCH ;;Search files & dirs in curr | | ;;--------------------------- | | | | cposn ,%w2 ;;position to start of window | | echo %dd%cd\; ;;display current directory | | ceol ;;clear to end of line | | do %mask ;;do files in curr directory | | cposn ,%w2 ;; position to start of win | | echo %dd%cd\%de ;; display the found file | | enddo ;;end of do block | | do *.*/d ;;do any subdir's in this dir | | cd %de ;; change into found dir | | gosub search ;; recurse to us for each dir | | 114 Macro Language - Examples ---------------------------------------------------------------------- cd .. ;; return to prev directory | | enddo ;;end of do block | | return ;;return from this procedure | | | | ;------------------------------------------------------------------- | | :DISPLAY_SCREEN ;; Redraw Main screen | | ;;--------------------------- | | | | cls 3,1,176 ;;clear the screen | | csroff ;;turn cursor off | | window 1,1,3,80,1,3,1,1 ;;display top box on screen | | cposn ,40 ;;position to screen center | | echoc Macro File Search ;;display screen title | | rstwin /n ;;free window, leave screen | | window 6,5,23,76,15,1,11,1 ;;display main window | | menucolor 15,4,0,14,2 ;;set menu color for prompts | | return ;;return with window active | | | | ;------------------------------------------------------------------- | | :DISPLAY_PAUSE ;; Display Pause Message | | ;;--------------------------- | | | | echo ;;drop a line | | if %cl>%w3 echo %(32); ;;if win is full, scroll it | | savvid ;;sav vid state on win stack | | cposn %w3,%w2-1 ;;position at bottom of win | | color 7,0/r ;;set rev video, blk on wht | | ceol ;;clear current line in it | | cposn ,%w4-%w2/2+%w2 ;;position to center of win | | echoc Press Return to Continue; ;;display prompt | | %k= ;;reset last key pressed | | do while %k<>%(27) .and. %k<>%(13) ;;while not Esc or Ret | | %k=%kb ;; %k = next keypress | | enddo ;;loop if not Esc or Ret | | rstvid ;;restore previous colors | | savvid ;;save video state again | | cposn %w3,%w2-1 ;;position at bottom of win | | ceol ;;clear off our prompt text | | rstvid ;;restore video state | | return ;;return to caller | | `---------------------------------------------------------------------' Since this example macro file is designed to return to the previous macro file when it finishes searching, and thus has no regular function key definitions, a little extra effort is necessary to trap errors and the Escape key so that the [FILEAUTO] definition can't terminate unexpectedly, leaving this macro file active because a RETURN command wasn't issued. 115 Macro Language - Technical Tricks ---------------------------------------------------------------------- Macro Technical TricksMacro Technical Tricks This section is provided to further augment the technically inclined. It discusses some tricks that may be well beyond average use. If while browsing through this section some of the material leaves you somewhat mystified, don't lose any sleep over it. Testing on the Extension of a FilenameTesting on the Extension of a Filename Occasionally it is useful to test on the extension of a selected file or tagged file to make sure its of the type that the macro key deals with. This can be done by using a combination of the two variables that return the filename with and without its extension. For example: IF %FE<>%FN.ZIP ECHO File is Not a .ZIP File. - or for tagged files - IF %TE<>%TN.ZIP ECHO File is Not a .ZIP File. Collecting Tagged Filenames into a Temp VarCollecting Tagged Filenames into a Temp Var ,---------------------------------------------------------------------, [F1] ZIP TAGGED FILES/w ;;TITLE LINE AND SWITCHES | | GET %FILE Enter Zip Filename: ;;GET DEST FILENAME IN %FILE | | :LABEL1 ;;LABEL FOR LOOP | | %LIST=%LIST %TE ;; %LIST=ITSELF+NEXT TAG FILE | | IF %SL(%LIST)>110 THEN ;; IF LONGER THAN 110 CHARS | | BEEP ;; BEEP | | MENU Command Line Length Exceeded ;; USE MENU TO DISPLAY | | .Press Return to Continue ;; THE ERROR | | EXIT ;; AND EXIT | | ENDIF ;; END OF IF BLOCK | | LOOP LABEL1 ;;LOOP THROUGH TAGGED FILES | | PKZIP -EX %FILE %LIST ;;ZIP THE TAGGED FILES | | `---------------------------------------------------------------------' Occasionally, it is useful to collect the tagged filenames into a user variable so that they can be processed simultaneously rather than re- executing a program several times with a different filename in a loop. In the example above, %LIST is added with itself plus the next tagged filename (%TE) until all tagged filenames have been added to %LIST by the loop. There is a limitation though. MS-DOS only provides for a maximum command line length of 128 bytes (which is the size of its field in the PSP), which is why the string length of %LIST is checked every time its expanded. A value of 110 was used instead of 128 116 Macro Language - Technical Tricks ---------------------------------------------------------------------- because when we run PKZIP, we're also passing it a filename in %FILE, and using some other switches. Executing Other than .COM or .EXEExecuting Other than .COM or .EXE If you rename the extension of a executable program to something other than .COM or .EXE, it is still possible to execute the program with a macro key, as long as you include the extension with the program's name on the macro line that runs it. This would allow you to rename potentially dangerous programs so that they can't be executed from the MS-DOS command prompt, but can still be used in the controlled environment of a macro key. For instance, if you wanted to restrict people from using the MS-DOS format command unless its run by a macro key, you could rename FORMAT.EXE to something like FORMAT.PRG (which would not be considered executable by any other shell since it now does not end with a .COM, .EXE, or .BAT extension) and then run it from a macro key by spelling out its full name (e.g. FORMAT.PRG A:/4). Temporarily Changing COMSPECTemporarily Changing COMSPEC ,---------------------------------------------------------------------, [F1] TELIX ;;TITLE LINE AND SWITCHES | | CDD C:\TELIX ;;CHANGE DRIVE & DIRS | | %OLD_COMSPEC=%[COMSPEC]%OLD_COMSPEC=%[COMSPEC] ;;%OLD_COMSPEC=ORIG COMSPEC | | SET COMSPEC=C:\DCOM\DCOM.COMSET COMSPEC=C:\DCOM\DCOM.COM ;;COMSPEC=DCOM | | TELIX ;;RUN TELIX | | SET COMSPEC=%SET COMSPEC=%OLD_COMSPEC ;;RESTORE ORIGINAL COMSPEC | | CD C:\ ;;CHANGE C: BACK TO ROOT DIR | | CDDO ;;RETURN TO ORIG DRIVE & DIR | | `---------------------------------------------------------------------' Occasionally, it may be desirable to temporarily change the contents of an environment variable such as COMSPEC or PATH. This can be done by saving its original value in a user variable before modifying the particular environment variable. A lot of programs use the COMSPEC variable to run a second copy of COMMAND.COM when they "Drop to DOS". Sometimes you can temporarily change COMSPEC to point to your favorite shell rather than COMMAND.COM so that when the program thinks its shelling out to DOS, its actually running another copy of your favorite shell. In this example, we used %OLD_COMSPEC to temporarily hold the contents of the COMSPEC variable. Then, we changed COMSPEC to point to dCOM so that when the Alt-J (Jump to DOS) command of Telix is invoked, instead of running COMMAND.COM and giving you the DOS prompt, it runs a second copy of dCOM. After Telix terminates, the COMSPEC variable is restored to its original contents held in %OLD_COMSPEC. 117 Macro Language - Technical Tricks ---------------------------------------------------------------------- Appending to an Environment VariableAppending to an Environment Variable You can easily append to the current contents of an environment variable by using the following technique: SET PATH=%[PATH];C:\UTILITYS In this example the PATH environment variable is appended with "C:\UTILITYS" by setting it with itself plus the text we want to add. This example is provided mainly to demonstrate how to do this with environment variables. The macro language actually provides an easier way to append entries to the environment path by using its PATHADD command. 118 ====================================================================== MENUINGMENUING ====================================================================== 119 Menuing - Overview ---------------------------------------------------------------------- Menuing OverviewMenuing Overview dCOM didn't originally start out with the intent of providing a powerful menu system. But one thing lead to another.... What dCOM did originally start with was a very simple macro capability. Well..., the macro capability has grown a lot since then and is now a powerful language. So it soon became clear that an option was needed that allowed the macro keys to be easily presented as a front-end menu. This is where the menu mode comes in. When dCOM is started in the menu mode (instead of starting as a file handler), it starts up displaying a menu of the 20 function key titles in the current macro file. Each of the 20 function keys can be configured to run a particular program, or branch off to a new macro file and display a whole new menu of options, or anything else you can make a function key definition do. The default appearance of the menu mode takes a rather "straight- arrow" approach, by showing the title of the active macro file centered above each of its macro key titles. There are plenty of options though which let you customize it. For more information refer to Controlling Menu Appearance on page 122. ,---------------------------------------------------, | MAIN MENU | |---------------------------------------------------| | F1 | Wordperfect | Tutorials | | F2 | Microsoft Word | -------------------- | | F3 | -------------------- | Communications | | F4 | dBase | Financial Mgmt | | F5 | -------------------- | -------------------- | | F6 | Harvard Graphics | Format a Disk | | F7 | Lotus 1-2-3 | Copy a Disk | | F8 | Quatro Pro | Search for a File | | F9 | -------------------- | -------------------- | | F10 | Windows | Ship Hard Drives | `---------------------------------------------------' Underneath this simple looking menu though are a lot of powerful features. For instance, the whole thing is natively mouse sensitive. You can execute a function key by clicking the mouse left button on its title. The right mouse button escapes gosub'd menu's or exits the menu mode. You can also execute function keys by using the cursor keys to select the title desired and press Return. Function key titles can also be highlighted by pressing the first letter of their text. When the right key is highlighted, press Return. Or, you can just press the appropriate function key. 120 Menuing - Menu Mode ---------------------------------------------------------------------- The Menu ModeThe Menu Mode The menu mode is activated by using the /M command line switch when you run dCOM. dCOM continues to stay in the menu mode unless the root (first) menu is escaped. When the menu mode is escaped, the file handler activates allowing you to quickly go find a file, copy a file, etc.... When you need to return to the menu mode, you simply press Escape again. ,---------------------------------------------------------------------, NOTE: If the login system is active, some users may not have the | | option of escaping the menu mode. | | `---------------------------------------------------------------------' Basically all there is to the menu mode is that you're telling dCOM to start up with a menu of the macro key titles on the screen. When you select an option - you're running a macro key. Typically, these would be simple macro keys that just run programs. But that doesn't have to stop you.... Building layered (multiple) menu's is performed using GOTOMF or GOSUBMF macro commands, which cause another macro file to load and become the active macro file. The difference between GOTOMF and GOSUBMF is that GOSUBMF saves the current macro filename on a gosub stack, which can later be returned to using a macro RETURN command (or pressing Escape from the menu). GOTOMF only changes the active macro file. The gosub stack can hold approximately 9 levels of gosub'd menus. GOSUBMF is the normal method of building layered menu's because it provides an easy mechanism to return to the previous macro file. It also has an optional switch (/C) that causes the new macro file's menu to display cascaded one level down and to the right so that the user can keep track of where they are in the menu structure. ,---------------------------------------------------------------------, NOTE: When the menu mode is active, you cannot use macro keys that | | were written to use the %FN, %FE, %TN, %TE, and %TC macro | | variables. These variables allow a macro key to interact with | | the file handler by returning the names of the selected file | | or tagged files, but they are meaningless when the menu mode | | is active. | | `---------------------------------------------------------------------' 121 Menuing - Controlling Menu Appearance ---------------------------------------------------------------------- Controlling Menu AppearanceControlling Menu Appearance As mentioned previously, the default appearance of the menu mode is somewhat on the 'plain Jane' side. If you're inclined to spiff it up a little more to your liking, there is a special macro definition, [MENUAUTO], which lets you customize the appearance of the screen displayed. [MENUAUTO] is a macro definition that executes just prior to when the menu will be displayed. In it, you can use macro commands that; clear the screen in a color more suiting your taste, display other windows of information, and override the color of the menu itself. For example: ,---------------------------------------------------------------------, MAIN MACRO'S ;;MENU TITLE | | | | [MENUAUTO] ;;RUNS BEFORE MENU DISPLAYS | | CLS 0,1,176 ;;CLS IN BLACK ON BLUE w/'░' | | WINDOW 1,1,4,80,1,7,1,1 ;;DISPLAY A BOX ON THE SCREEN | | ;; AND THEN DISPLAY VERSION | | ECHO dCOM Menu System Ver %SS(%DV,1,1).%SS(%DV,2,2); | | CPOSN ,78 ;;POSITION TO RIGHT EDGE | | ;; THEN DISPLAY DATE & TIME | | ECHOR %DW, %MY %SS(%DT,4,2), 19%SS(%DT,7,2) %TI; | | CLOCK %CL,%CC-8 ;;TURN CLOCK ON | | CPOSN 3,3 ;;MOVE CURSOR TO NEXT LINE | | ECHO Current User %LN; ;;DISPLAY USER NAME | | CPOSN ,78 ;;POSITION TO RIGHT EDGE | | ;; THEN DISP FREE DISK SPACE | | ECHOR %FC(%FD(C)) Free of %FC(%TD(C)) On Drive C: | | RSTWIN /N ;;FREE WINDOW, LEAVE SCREEN | | MENUSTART 8,14 ;;SET MENU DISPLAY POSITION | | MENUCOLOR 0,3,1,14,2 ;;SET MENU COLORS/BORDER TYPE | | | | [F1] MS-WORD ;;TITLE LINE AND SWITCHES | | CDD C:\MSWORD ;;CHANGE DRIVE & DIRECTORIES | | WORD ;;RUN MS-WORD | | CD C:\ ;;CHANGE C: BACK TO ROOT DIR | | CDDO ;;RETURN TO ORIG DRIVE & DIR | | . | | . | | `---------------------------------------------------------------------' If you gosub other menu's (macro files) from a macro file that uses a [MENUAUTO] definition, the gosub'd macro files should also contain a copy of the same [MENUAUTO] definition (especially if the [MENUAUTO] definition contains a MENUSTART command). 122 Menuing - Include Files ---------------------------------------------------------------------- Include FilesInclude Files Having a bunch of macro files that all use the same [MENUAUTO] definition however, could become a little difficult to maintain (like when you suddenly decide you'd rather use a different set of colors). So you may want to put the [MENUAUTO] definition off in its own file and then INCLUDE it in each macro file that needs it. For example: ,---------------------------------------------------------------------, ;=================================================================== | | ; DCOM.MAC | | ;------------------------------------------------------------------- | | INCLUDE MENUAUTO.INC ;;INCL [MENUAUTO] DEFINITION | | | | [F1] MS-WORD ;;TITLE LINE AND SWITCHES | | CDD C:\MSWORD ;;CHANGE DRIVE & DIRECTORIES | | WORD ;;RUN MS-WORD | | CD C:\ ;;CHANGE C: BACK TO ROOT DIR | | CDDO ;;RETURN TO ORIG DRIVE & DIR | | | | . | | . | | | | `---------------------------------------------------------------------' ,---------------------------------------------------------------------, ;=================================================================== | | ; MENUAUTO.INC | | ;------------------------------------------------------------------- | | ; Description: | | ; | | ; This is the standard [MENUAUTO] definition. This file is | | ; INCLUDE'd by all macro files which need it. | | ; | | ;------------------------------------------------------------------- | | [MENUAUTO] ;;RUNS BEFORE MENU DISPLAYS | | CLS 0,1,176 ;;CLS IN BLACK ON BLUE w/'░' | | WINDOW 1,1,4,80,1,7,1,1 ;;DISPLAY A BOX ON THE SCREEN | | ;; AND THEN DISPLAY VERSION | | ECHO dCOM Menu System Version %SS(%DV,1,1).%SS(%DV,2,2); | | CPOSN ,78 ;;POSITION TO RIGHT EDGE | | ;; THEN DISPLAY DATE & TIME | | ECHOR %DW, %MY %SS(%DT,4,2), 19%SS(%DT,7,2) %TI; | | CLOCK %CL,%CC-8 ;;TURN CLOCK ON | | CPOSN 3,3 ;;MOVE CURSOR TO NEXT LINE | | ECHO Current User %LN; ;;DISPLAY USER NAME | | CPOSN ,78 ;;POSITION TO RIGHT EDGE | | 123 Menuing - Include Files ---------------------------------------------------------------------- ;; THEN DISP FREE DISK SPACE | | ECHOR %FC(%FD(C)) Free of %FC(%TD(C)) On Drive C: | | RSTWIN /N ;;FREE WINDOW, LEAVE SCREEN | | MENUSTART 8,14 ;;SET MENU DISPLAY POSITION | | MENUCOLOR 0,3,1,14,2 ;;SET MENU COLORS/BORDER TYPE | | `---------------------------------------------------------------------' There is one drawback though to using included files. dCOM does not automatically recognize when changes have been made only to the include file. Its means of detecting whether the .CMF file is current is to compare the date stamp of the .MAC file against its .CMF file. It has no way of knowing that a .MAC's .CMF file was also built from files other than the .MAC file. If you change an included file without changing the .MAC file that calls it, the changes won't take effect until something modifies the date stamp of the .MAC file, or you use the macro RECOMPILE command. For example: ,---------------------------------------------------------------------, [F1] RECOMPILE MACROS ;;TITLE LINE AND SWITCHES | | RECOMPILE *.MAC /v ;;RECOMPILE ALL .MAC FILES | | `---------------------------------------------------------------------' Based on this, using included files would appear to be an attractive option mainly when the contents of the included file are relatively stable. Although our discussion on using include files so far has been in conjunction with [MENUAUTO], you can easily throw other definitions in an include file as well. For instance, a set of common subroutines could be built under a [PUBLIC] definition, which sits off in another file and is included by macro's that need access to the subroutines. The same goes for using values that need to be consistent across several macro files by building them under a [EQUATES] definition and then including them in each macro file. 124 ====================================================================== ACCESS CONTROLACCESS CONTROL ====================================================================== 125 Access Control - Overview ---------------------------------------------------------------------- Access Control OverviewAccess Control Overview If we could all trust one another wouldn't life be great.... But sometimes we don't, especially with our own personal computer. dCOM's access control (login) system allows you to define each user that needs to access the computer, and just what they can do when they use dCOM. Individual rights control what the user can do while they are in the file handler (or if they can access the file handler at all). These are things like whether the user can open files (copying, printing, editing, etc...), modify files (delete, rename, move, hide, or editing w/save), change configurations, save configurations, run programs, and view hidden files. Groups can be used to restrict certain menu (macro) options based on whether the user belongs to a group in the set specified by a macro's /G title line switch. You can also enable the access control system with several additional features. One of them automatically logs the user out if the screen saver times out due to inactivity. Another feature automatically blanks the screen and locks the keyboard (until the user retypes their password), if the screen saver times out. Enabling the access control system can serve a variety of needs. Some people may just wish to have their computer password protected when it is first turned on. Others, may have more of a concern with what capabilities are available to other users using their computer. Or, from a menuing perspective, what menu functions are available to which users. And lastly, maybe just keeping track of usage (which users were on when and what programs they ran) by also activating the activity log with the /A command line switch.. Aside from physical or hardware security measures, most software-based passwording systems are penetrable in one way or another. dCOM's access control system is most effective when you load dCOM as the primary shell with a SHELL= statement in CONFIG.SYS. This pretty much covers all bases except booting off a floppy, because the CONFIG.SYS file can't be aborted with a CtrlC. The access control system wasn't intended to be an absolutely fool proof solution to keeping out unwanted hackers. But it is real good at keeping honest users honest. You can provide users an option to change their password by using an undocumented command. 126 Access Control - Enabling ---------------------------------------------------------------------- Enabling Access ControlEnabling Access Control Running dCOM with the access control system enabled is done by passing it a /L, or /LA command line switch. The /L switch enables the basic access control system. The /LA switch enables the access control system with an automatic time-out feature that logs the user out if the computer is inactive long enough to trip the screen saver. ,---------------------------------------------------------------------, NOTE: In order for the automatic logout feature to activate, dCOM's | | screen saver must be enabled. Also, the automatic logout only | | occurs if the file handler or menu mode are currently active. | | If an external application is active, only the screen saver | | will activate. | | `---------------------------------------------------------------------' When you run dCOM, there are several ways to pass it command line switches. If you use the DCOM environment variable or the SWITCHES.SYS file, to specify the /L or /LA switches, the effect will be that if you exit dCOM and rerun it, the access control system will still be active and the login prompt will be reissued. If these switches are passed on the command line that runs dCOM in AUTOEXEC.BAT, the first time dCOM runs you will be prompted for a login name, but if you exit dCOM for one reason or another and then rerun it, the login system won't be active the 2nd time and you won't be prompted to login again. Both of the login command line switches also accept parameters that allow you to include a default user's name and password. (Giving both the user name and password is somewhat self-defeating though.) The full syntax of the access control switches is: /L[:name][,password] /LA[:name][,password] If a default name is included with these switches and that name in the Access Control Menu's user list has no password, the login will proceed automatically without displaying a login prompt, otherwise the default name is filled in and the login prompt starts up asking for the password. If a default name is included that doesn't exist in the user list, dCOM will attempt to automatically proceed and log the user in as GUEST. 127 Access Control - Logging In ---------------------------------------------------------------------- Access Control Logging InAccess Control Logging In When the access control system is enabled, the first thing dCOM does when it starts up is prompt for the user to log in. Whether an unknown name is allowed to log in depends on whether you leave the GUEST user active in the access control menu's user list. If the GUEST user is not deleted from the user list, three unsuccessful login attempts will proceed with the user logged in under GUEST. If the GUEST user is deleted, the login prompt will not proceed until a valid user is logged in. If the user enters a valid name which has no password entered in the user list, dCOM will proceed to log the user in without prompting for a password. If the user enters an invalid name, dCOM will act dumb and proceed to prompt for the password, which will of course then fail. Successful login's are automatically logged to the log file (DCOM.LOG) if the Audit Trail feature is enabled (dCOM's /A command line switch). Active PasswordActive Password When the access control system is enabled, the active password is that of whoever is logged in. When the access control system is disabled, the active password is that of the SUPERVISOR's entry. Currently, the active password is only used to unblank a blanked screen. The screen can be blanked and the keyboard locked at any time by pressing the Shift-Ctrl-B hotkey. If dCOM's /SB command line switch was also specified at start up, the screen blanker will also activate when the screen saver times out. 128 Access Control - Logging Out ---------------------------------------------------------------------- Access Control Logging OutAccess Control Logging Out An Alt-L may be issued whenever the menu mode or file handler screens are active, to log the current user out and then display a prompt to log back in as a new user. If the automatic logout switch was used (/LA) and the screen saver trips due to no keyboard or mouse activity, the user will be logged out automatically. When the screen is restored (by pressing any key), the login prompt will then be displayed. (Automatic logouts may be inhibited by using the Shift-Ctrl-B hotkey to blank the screen.) Logging a user out can also be done during macro execution by using an undocumented command in a macro key. Or, by configuring a macro key with the /L title line switch and just executing it. When a logout occurs with the menu mode enabled, but the user had escaped back to the file handler, if the next user that logs in doesn't have rights to the file handler the menu mode will automatically be reactivated. If an automatic (screen saver time-out) logout occurs while in the menu mode and the current macro file is a gosub'd macro file, dCOM will automatically return to the root macro file after a new user logs in (except if the next paragraph applies). If any type of logout occurs and a macro file called LOGIN.MAC exists in dCOM's Home Directory, it will become the root macro file causing any gosub'd macro files to be discarded. For more information refer to page 14. Internal hard disks are automatically parked (shipped) when a logout of any type occurs. Logouts are automatically logged to the log file (DCOM.LOG) if the Audit Trail feature is enabled (dCOM's /A command line switch). 129 Access Control - Administration ---------------------------------------------------------------------- Access Control AdministrationAccess Control Administration Configuring the access control system is done in the file handler's Alt-A - Access Control Menu. When the access control system is enabled, only someone logged in as a supervisor or junior supervisor may enter and edit the Access Control Menu. If the access control system is not enabled, the active password (which will be the SUPERVISOR's password) will be prompted for (if its been set), before entry is allowed. If the access control system is enabled and the user currently logged in is not a supervisor, pressing Alt-A to invoke the Access Control Menu will only display a window showing the current user's name, rights, and groups. Under the Access Control Menu you define a list of users that will have access to the computer, and what privileges they will have. The Access Control Menu initially defaults with two entries, SUPERVISOR and GUEST. Both entries play a role under different situations and shouldn't be deleted carelessly. The SUPERVISOR's password is used as the active password when the access control system is not enabled. One of the first orders of business should be to enter a password for the SUPERVISOR entry so that other users can't log in using its name. The GUEST user controls what rights and groups an unknown user will have, if it exists. If you don't wish to allow invalid login's, then delete the GUEST entry. If there are a large number of users fitting a general description of "peon", instead of building all their names in the user list, you could just tell them all to log as GUEST. Be sure to configure the GUEST entry to only have the rights and groups with which you are comfortable if an unknown user is on your system. Normally, the primary supervisor would immediately add his/her name in the user list and give themselves a group flag of "$" (making their name a supervisor with full access to the system). If the primary supervisor wants to further delegate some junior supervisors, he/she would add their names to the user list and give them a group flag of "#", which gives them the same full access as the supervisor except that they cannot modify other users having supervisor, or junior supervisor group flags. 130 Access Control - Administration - Rights ---------------------------------------------------------------------- RightsRights User rights control what capabilities a user has when they are in the file handler, or whether they can even access the file handler. F - File HandlerF - File Handler. This right controls whether the user has access to the file handler. If a user is not given this right, they will not be allowed to escape the menu mode or, if the menu mode isn't active, they will be denied access to log in. (Note: If you are preventing people from accessing the file handler, you should ensure that the GUEST entry cannot do so either.) R - Run ProgramsR - Run Programs. This right is required to run external programs or issue DOS commands. X - ExitX - Exit. This right controls whether the user can exit dCOM. O - Open FilesO - Open Files. This right is required to copy files, print files, edit or browse files, etc.... It basically controls whether the user can in any way read or view the contents of a file. M - Modify FilesM - Modify Files. This right is required to delete files, rename files, move files, edit and save a file, change file attributes, etc.... It basically controls whether the user can in any way change something related to files. C - Change ConfigurationsC - Change Configurations. This right is required to view and/or change any of the configuration menus. S - Save ConfigurationsS - Save Configurations. This right is required to permanently save changes made to any of the configuration menus. V - View Hidden FilesV - View Hidden Files. This right is required in order for the user to change the view mode to show hidden files. 131 Access Control - Administration - Groups ---------------------------------------------------------------------- GroupsGroups Groups are a set of one or more flags which you assign to each user. Some of the group flags can also influence user rights. There are three different types of group flags; Standard Groups (A...Z), Auto Rights (1...4), and supervisor ($ or #). Standard Group flags only apply to macro key definitions that use a /G title line switch. If a macro key uses the /G title line switch, the user must also belong to one of the groups listed after the /G in order to access the macro key. For example: ,---------------------------------------------------------------------, Name Groups Sample Macro Definition | | | |-----------------------+---------------------------------------------| JOE AB1 [F1] Personnel Data /G:AC | | | MIKE C2 CDD C:\PERSONEL | | | PETE B DBASE MYPROG | | | RALPH BD2 CD C:\ | | | SANDY A1 CDDO | | | `---------------------------------------------------------------------' In the example above, Joe, Mike, and Sandy would have access to the F1 key because one or more of their group flags contains either an "A" or "C". Pete and Ralph do not, and when they are logged in the F1 key will appear blank. Use of the Standard Groups (A...Z) is purely arbitrary. dCOM makes no significance on their use other than what you do with them in conjunction with the macro /G title line switch. Auto Rights Group flags (1...4) are provided as a shortcut for quickly giving a user some pre-configured rights in the file handler. For instance, if you wanted to give someone File Handler, Open, and Run rights, all you could just give them a group "2" instead of turning on each of these rights individually. Supervisor group flags ($ or #) automatically give a user full access to the entire system. The only difference is that the "$" group is a full supervisor and the "#" is a junior supervisor. Junior supervisor's can't change other supervisor records and can't create new supervisors. 132 Access Control - With the Macro System ---------------------------------------------------------------------- Access Control With the Macro SystemAccess Control With the Macro System The access control system can be used to control which users can access certain macro keys. Function keys are normally accessible to all users unless they are protected with the macro /G title line switch. (This was just discussed on the previous page.) You can provide menu options to log users out and in using two different methods: * You could use an undocumented command which logs the user out, clears the screen, ships the hard drives, and presents a login prompt for the next user. * You can configure a macro key with a /L title line switch. This switch provides a quick method of turning a macro key into means of logging users in and out of the access control system. ,---------------------------------------------------------------------, NOTE: Any time the menu mode is active, an Alt-L can also be pressed | | to logout and log back in as a new user. This option is | | supplied as a fail-safe measure in case you're currently | | logged in as user that doesn't have file handler rights and | | for some inexplicable reason there aren't any macro options to | | log back in as a supervisor.... | | `---------------------------------------------------------------------' When you use the /L title line switch on a macro key definition, the key becomes a special login/logout macro key. The macro definition need not be followed by executable macro code (if it does, it won't execute), the presence of the switch alone is all that is required. When a macro key is executed that has a /L title line switch and a user is currently logged in, the user is logged out and all other function key titles disappear (the menu mode is now locked in place until a new user logs in). When the same macro key is executed again, the login prompt for a new user is then displayed. Another feature of the /L title line switch is that the title of the macro key is managed for you (either "Login" or "Logout" is automatically displayed depending on what the next logical action should be). The only reason for entering a title with the /L switch is to give dCOM a template which shows whether to display the automatic title in uppercase, lowercase, or some mix thereof. From within a macro key you can access the currently logged user name with the %LN system variable. 133 ====================================================================== APPENDICESAPPENDICES ====================================================================== 134 Appendix A - Using Macro Files on a Network ---------------------------------------------------------------------- Appendix A - Using Macro Files on a NetworkAppendix A - Using Macro Files on a Network dCOM can easily drive a network menu system by having the network macro files located in a public subdirectory on a network drive. More on this in a little bit. dCOM generically is very network friendly. It always opens and reads files (like its overlay and macro files) in read-only compatibility mode, which is normally considered shareable by most network operating systems. Furthermore, it almost always reads files with one quick read instruction and then immediately closes them. The window of opportunity for a conflict is very small, even if a network didn't consider files opened for reading as shareable. dCOM never has a file open when its sitting static waiting on the keyboard (or mouse). You can always edit macro files placed on a network drive without worrying about file sharing problems. If your network operating system is Novell, dCOM has a powerful set of additional macro commands and system variables, that let your macro keys operate a lot smarter about who the current user is, who other users are, etc.... dCOM's macro language directly supports all of the login script functions and it does it more than 10 times faster. Other macro commands provide access to the bindery directly, letting you DO loops around any bindery object, or display menu selections of any bindery type (e.g. print servers, print queues, file servers, users, groups, etc...). Documentation on these capabilities is supplied separately in a package called dCOM For NetWare. You can install dCOM on local workstations and easily configure a local macro key to call the network menu by using a macro GOSUBMF command. The only directory privilege required in a shared network macro directory is Read. This keeps unwanted eyes from being able to view the details of your network macro's because they probably will have no idea what the macro filenames are (except for the first one called). Whenever you use the GOSUBMF command to call a macro file on the network, you must specify the full path to the macro file (otherwise dCOM will try to find the macro file in its Home Directory). 135 Appendix A - Using Macro Files on a Network ---------------------------------------------------------------------- For example: ,---------------------------------------------------------------------, [F10] NETWORK MENU ;;TITLE LINE AND SWITCHES | | IF NOT EXIST N:\NUL ;;IF NETWORK DRV NOT PRESENT | | BEEP ;; BEEP | | MENU Not Logged into Network ;; DISPLAY MESSAGE USING | | .Press Return to Continue ;; MENU COMMAND | | EXIT ;; TERMINATE THE MACRO | | ENDIF ;;END OF IF BLOCK | | GOSUBMF N:\MENU\MAINMENU.MAC ;;CALL THE NETWORK MENU MACRO | | `---------------------------------------------------------------------' On a Novell network, you can use volume references instead of drive references when calling macro files (for that matter, you can use them almost everywhere else too). For example: ,---------------------------------------------------------------------, [F10] NOVELL NETWORK MENU ;;TITLE LINE AND SWITCHES | | IF %FS="" THEN ;;IF FILE SERVER NOT PRESENT | | BEEP ;; BEEP | | MENU Network Drivers Not Loaded ;; DISPLAY MESSAGE USING | | .Press Return to Continue ;; MENU COMMAND | | EXIT ;; TERMINATE THE MACRO | | ENDIF ;;END OF IF BLOCK | | GOSUBMF SYS:MENU\MAINMENU.MAC ;;CALL THE NETWORK MENU MACRO | | `---------------------------------------------------------------------' These examples are not meant to be fully working models. They are provided mainly to exhibit a rough sketch of how it can be done. There is one thing to always keep in mind on a network though. Wherever you put the network .MAC files is where dCOM will try to build their equivalent .CMF files (compiled macro files). If you (the supervisor) modify the .MAC file, you should immediately run that macro file so that your network access can build the .CMF file. In all likely hood, the privileges you've granted to regular users won't let their access build the .CMF file. (You should run the macro anyway just to test your changes.) 136 Appendix A - Using Macro Files on a Network ---------------------------------------------------------------------- What happens when a .MAC file has been modified and is out of sync with its .CMF file under a regular user's privileges, is that their copy of dCOM will detect that its out of sync and automatically invoke their macro compiler (when they attempt to access it), the macro compiler will properly build their memory image of the .MAC file but it won't be able to save the .CMF file. When this happens, dCOM doesn't produce any superficial indication that it couldn't write the .CMF file. The only symptom is that access to the .MAC file by regular users can become noticeably slower (depending on how big it is) until the .CMF file can be properly written under a supervisor's access. When the .CMF file is in sync with the .MAC file, dCOM can directly load the .CMF file into memory without spending time loading the macro compiler overlay and then doing the actual compilation. 137 Appendix B - Batch File Interchangeability ---------------------------------------------------------------------- Appendix B - Batch File InterchangeabilityAppendix B - Batch File Interchangeability Most batch files can be directly imported as macro files with little or no modification. dCOM's macro language is almost 100% compatible with the MS-DOS batch language. Batch file commands that are not directly compatible with the macro language are: CALLCALL This batch command calls another batch file, allowing the current batch file to resume when the called batch file terminates. In the macro language you would delete the "CALL" portion of the command and just say the batch file's name as a macro command. If a CALL command is left in place, it should still function properly to call the specified batch file. FORFOR This batch command allows a DOS command to execute repeatedly for every item produced in a data set. In the macro language this capability is emulated by the DO or DO WHILE commands, which allow multiple commands inside nestable DO blocks. If a FOR batch command is left in place, dCOM will call a copy of COMMAND.COM to execute it, usually with the same results. Some conversion effort will be required if you want to translate a batch FOR command to a macro DO command. SHIFTSHIFT This batch command shifts the command line variables passed to a batch file in %1...%9 down a notch. They would roughly be equivalent to the macro's %P1 through %P9 variables, but there is no macro equivalent for this command. IFIF A batch file IF command requires two consecutive equals signs to delimit the operands being compared. The macro language only requires one, but won't argue about finding two of them. A batch file can't do greater than or less than tests, just case-sensitive equality tests. The macro IF command is not case sensitive and does these tests as well as compound, nestable IF block structures. Another syntax difference is that a batch file lets you start a command with an "@" symbol in order to keep the batch command itself from echoing on the console when the echo mode is on. The macro language does not have an echo mode and doesn't echo its macro commands to the screen, so this option is meaningless. It the "@" symbol is encountered as the first significant character of a macro command, the "@" symbol is ignored but the command still executes. 138 Appendix C - The Internal Macro Compiler ---------------------------------------------------------------------- Appendix C - The Internal Macro CompilerAppendix C - The Internal Macro Compiler Understanding how the internal macro compiler works can prove helpful from time to time. It has already been discussed somewhat in several other sections, like the one previous. The macro compiler is one of many overlays that are all merged together in the DCOM.OVL file. When dCOM tries to load a macro file, either because it wants to load the default macro file, or because the user initiated an action like the file handler's "/" command, or because the current macro file used a GOSUBMF command (these are all just examples), dCOM looks for a file with a .CMF (compiled macro file) extension that matches the filename of the .MAC file being loaded. If it can find the .CMF and if it has the same date stamp as the .MAC file, the .CMF file will be loaded directly into memory and the operation is done with. If it can't find the .CMF file or the date stamps don't match, dCOM automatically invokes the macro compiler against the .MAC file. After the compiler finishes building the .MAC file to a memory image, dCOM will attempt to save it out as a .CMF file using the same date stamp of the .MAC file. ,---------------------------------------------------------------------, NOTE: When .CMF files are initially created, they are given a hidden | | attribute. If you remove the hidden attribute on a .CMF file | | (the same as with other hidden files), dCOM will respect that | | and continue to leave it unhidden when it has to rewrite the | | .CMF file again. | | `---------------------------------------------------------------------' 139 Appendix D - ANSII Music ---------------------------------------------------------------------- Appendix D - ANSII MusicAppendix D - ANSII Music The macro BEEP command is capable of playing music in ANSI notation. This is done by following the beep command with the ANSI music text. If no text follows the BEEP command, the usual asynchronous system beep is sounded. For those not familiar with ANSI music notation, the following is a brief description: A..GA..G The musical notes A thru G. A note may be immediately followed by a modifier ("#" or "+" for sharp, "-" for flat). Next, a note may be followed by a number denoting the note length (1 for a whole note thru 64 for a 64th note). Lastly, a note may be followed by one or more periods ("."), each of which will extend the note by one half of its existing value. LnLn Specifies the default length of notes to follow ("n" is 1 for a whole note thru 64 for a 64th note). The initial default is 4 for a quarter note. OnOn Specifies the octave for notes to follow ("n" may be 0 thru 7). The initial default octave is 4, the same octave in which middle C is found. P[n]P[n] Specifies a pause (no sound). The optional "n", may be used to give a different note length from the current default (1 for a whole note thru 64 for a 64th note). One or more periods (".") may follow, each of which will extend the pause by one half of its existing value. TnTn Specifies the tempo in beats per minute (32 thru 255). The initial default is 120. For Example: ,---------------------------------------------------------------------, [F1] MUSIC? ;;TITLE LINE AND SWITCHES | | BEEP T240L3ABC#D ;;PLAY NOTES A, B, C#, AND D | | `---------------------------------------------------------------------' 140 Appendix E - Macro Error Numbers ---------------------------------------------------------------------- Appendix E - Macro Error NumbersAppendix E - Macro Error Numbers When a macro error occurs and an error trap has been set with ONERRORGOTO, the number of the error that occurred is available for testing in %EL (the error text is also available in %ET). Currently, this isn't too awfully useful because a majority of the errors will return a general DOS file system I/O error (#35) that doesn't really help identify what happened. Nevertheless, the possible error codes are provided here for what they may be worth. 1 INTERNAL MACRO ERROR 40 NOT LOGGED IN 2 ERROR CHANGING DIRECTORY 41 ERROR MAPPING VOLUME PATH 3 INVALID LEVEL 42 ERROR ATTACHING TO SERVER 4 LABEL NOT FOUND 43 <Unassigned> 5 COMSPEC NOT DEFINED 44 NETWORK DRIVERS NOT LOADED 6 BAD COMMAND OR FILENAME 45 SERVER NOT SPECIFIED 7 INSUFFICIENT MEMORY 46 ERROR READING CAPTURE FLAGS 8 ERROR LOADING PROGRAM 47 ERROR WRITING CAPTURE FLAGS 9 SYNTAX ERROR 48 INVALID PRINT QUEUE 10 ENVIRONMENT SPACE FULL 49 ERROR STARTING CAPTURE 11 ERROR OPENING REDIRECTION 50 INVALID CAPTURE FILE 12 NO FILES TAGGED 13 LOOP WITHOUT TAG VARIABLE(S) 14 TAG VARIABLE(S) WITHOUT LOOP 15 COMMAND LINE OVERFLOW 16 DO VARIABLE(S) WITHOUT DO 17 NO MATCHING ENDIF 18 NO MATCHING ENDDO 19 ENDDO WITHOUT DO 20 DO NEST LIMIT EXCEEDED 21 GOSUB STACK OVERFLOW 22 MACRO KEY MULTI-DEFINED 23 LABEL MULTI-DEFINED 24 FILE HANDLER VAR USED IN MENU 25 INVALID DRIVE 26 ERROR LOADING EDITOR OVERLAY 27 FILE NOT FOUND 28 SYNTAX ERROR IN FILE 29 OUT OF WINDOWING MEMORY 30 ERROR MAKING DIRECTORY 31 VAR EXPANSION STACK OVERFLOW 32 FILE NUMBER NOT OPEN 33 LINE TOO LONG IN READ FILE 34 READ PAST EOF 35 DOS FILE SYSTEM I/O ERROR 36 ILLEGAL VARIABLE NAME 37 DISK SPACE FULL 38 NO MATCHING IF..THEN 39 INVALID SEARCH DRIVE 141 IndexIndex ====================================================================== [DRIVEAUTO] 21 EXITDCOM 43 [EQUATES] 22, 124 GET 44 [FILEAUTO] 19 GETW 45 [MENUAUTO] 20, 122 GOSUB 46 [PUBLIC] 21, 124 GOSUBMF 47 Access Control GOTO 49 Active Password 128 GOTOMF 49 Administration 130 IF 50, 51, 52 Enabling 127 INCLUDE 53 Logging In 128 KEYBOARD 54 Logging Out 129 KEYWAIT 54 Overview 126 LOOP 55 With the Macro System 133 MACROMENU 55 Arithmetic 28 MD 56 In-Line 33, 39, 50, 60, 74 MENU 56 Array Variables 81 MENUCOLOR 58 AUTOEXEC.MAC 9, 13 MENUSTART 59 Batch File MENUTITLE 59 Interchangeability 138 MKDIR 56 Commands MUL 60 ADD 33 ONBREAKGOTO 60 APPMENU 33 ONERRORGOTO 61 BEEP 34 OPEN 62 BROWSE 34 PATH 63 CD 35 PATHADD 63 CDD 35 PATHDEL 64 CDDO 35 PAUSE 65 CLOSE 35 PRINTFIL 65 CLS 36 PRINTSTR 65 COLOR 36 PROMPT 66 CREATE 37 QFORMAT 66 DEL 37 RD 67 DELAY 38 READ 67 DELAYW 38 READB 67 DIV 39 READLN 68 DO 39 REBOOT 68 DO WHILE 40 RECOMPILE 69 ECHO 41 REM 69 ECHOC 41 RETURN 69 ECHOR 42 RMDIR 67 EDIT 42 RSTWIN 70 ELSE 42 RUNMACRO 70 ELSEIF 42 SELECT 70 ENDDO 43 SET 73 ENDIF 43 SHIP 73 ERASE 37 SUB 74 EXIT 43 VLIST 74 142 Index ---------------------------------------------------------------------- WINDOW 74 Menuing 120 WRITE 76 Macro Variables 78 WRITEB 76 Equates 22 Comments 12, 24 System Variables 82 Compiling Macro Files 9 User Variables 80 Ctrl-C Aborting 5 Arrays 81 Editing Macro Files 10 Indirect Assignments 81 Equate Variables 22 Menu Appearance 122 Error Messages 6 Menu Mode 120 Escape Trapping 6 Menu Title 12 Examples 101 Menuing Function Key Definitions Controlling Menu Appearance Overview 16 122 Special 18 Overview 120 [DRIVEAUTO] 21 The Menu Mode 121 [EQUATES] 22, 124 Menuing Switches 30 [FILEAUTO] 19 Menus and Windows 29 [MENUAUTO] 20, 122 Network [PUBLIC] 21, 124 Use 69, 92, 100, 135 Title Line Syntax 16 Password Protection 17 Function Key Titles 16 Pause Messages 6 IF Statements 26 Redirection 24 Compound 27 System Variables 82 In-Line Technical Tricks 116 Arithmetic 28, 33, 39, 50, 60, Title Line Switches 17 74 Password 17 Include Files 123 TSR Removal 17 Indirect Assignments 81 Wait 17 Introduction 2 Title Line Syntax 16 Leading Spaces 24 Titles LOGIN.MAC 9, 14 Function Key 16 Macro Command Reference 32 Menu 12 Macro Compiler 139 TSR Removal 2, 17 Macro Files User Variables 80 AUTOEXEC.MAC 9, 13 Using Macro Keys Comments 12 From the File Handler 7 Compiling 9 General Overview 5 Editing 10 Variable Types File Format 11 Equates 22 LOGIN.MAC 9, 14 System 82 Network Use 135 User 80 Overview 9 Arrays 81 Title Line Syntax 12 Indirect Assignments 81 Macro Key Definitions Variables 78 Password Protection 17 Reference Title Line Switches 17 %(###) 84 Macro Language %[var] 84 Command Reference 32 %AT 85 Examples 101 %C1..%C3 85 Overview 24 %CC 86 Technical Tricks 116 %CD 86 Macro System %CL 86 143 Index ---------------------------------------------------------------------- %DD 86 %XC 99 %DE 87 %XM 99 %DF 86 White Space 24 %DN 87 XM.SYS 99 %DP 87 %DS 87 %DT 87 %DV 88 %DW 88 %EL 88 %ET 88 %EX 89 %FA 89 %FC 90 %FD 90 %FE 90 %FM 90 %FN 90 %FP 91 %KB 91 %LC 91 %LD 92 %LE 92 %LN 92 %MM 92 %MY 92 %OD 93 %OS 93 %P1..%P9 93 %RJ 93 %RT 94 %SC 94 %SE 95 %SF 94 %SL 94 %SN 95 %SP 95 %SS 95 %TC 96 %TD 96 %TE 96 %TI 97 %TL 97 %TN 96 %TR 97 %UC 97 %var% 84 %VL 97 %W 97 %W1..%W4 98 %WD 98 %WT 98 144 Notes ----------------------------------------------------------------------